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The best tool for text. 

BBEdit. The premier text 8c 
HTML Editor for the Mac OS® 


From those who know... 


David Eddy Spicer 
Assistant Director, 

Case Program 
John F. Kennedy 
School of Government 
Harvard University 

“I use BBEdit every day and 
Tm continually blown away by 
the intelligent interface, the 
power user features like ‘grep’, 
search and replace across multiple 
files, the syntax coloring, the FTP 
open 8c save, the configurability, 
Internet Cx)nfig, everytliing. Every 
Lime T think of sometliing Fd like 
to see added to the program, I 
discover tliat it’s already there. 
You guys really thought of 
everything! When I use other 
programs, 1 find myself 
wishing for the features 
that BBEdit has.” 

Chris Varosy 
US Web/Dream Media 


<http://web.barebones.com/> 
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‘T’ve been using BBEdit for about a month and now 
find it invaluable. It seems to offer just the tools 1 
need not only for HTML coding (which is what 
I bouglit it for), but also for writing and 
research, which came as a surprise. 

As a devotee of light and flexible vs. 
bloated and unwieldy, I’ve taken to 
using BBEdit for the daily grind 
of my writing chores. When I 
get bored, I just turn to 'grep’ 
and toy with some complex 
search and replace expression! 

Thanks for your sofid work.” 


B Bare Bones Software, Inc. 

1.0. Box 1048, Bedford, MA 01730 • main 781-687-0700 • fax 781-687-0711 


BBEdit is a trademark of Bare Bones Software, Inc. "It Doesn’t Suck" is a registered trademark of Bare Bones Software, Inc. © 1998 Bare Bones Software, Inc. AH rights reserved. 






























^^ithout a doubly the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools, 

- MacUser Magazine Eddy Awai'ds 

'A disiincL improvement over Apple's ResEdit” 

- MacTecIi Magazine 

‘Every Mac OS developer should own a copy of Resorcerer," 

- Leonard Rosenthol, Aladdin Systems 

“Without Resorcerer, our localization efforts would look like a 
Tower of Babel, Don't do pi'oduct without it!" 

- Greg GalanoSy CEO and President, Metrowerks 

“Resorcerer's data template system, is amazing." 

- Bill Goodman, author of Smaller Installer and Compact Pro 

“Resorcerer Rocks! Buy it, you will NOT regret it." 

- Joe Zohkiw, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many times over in saved time and effort. 

- MacUser review 

“The template that disassembles PICT's is awesome!" 

- Bill Steinberg, author ofPyro! and PBTools A 

“Resorcerer proved, indispensible in its own creation!" 

- Doug McKenna, author of Resorcerer 




Version 2.0 



• Very fast, EDFS browser for viewing file tree of all volumes 

• Extensibility for new Resorcerer Apprentices (CFM plug-ins) 

• New AppleScript Dictionary (‘aete’) Apprentice Editor 

• MacOS 8 Appearance Manager-savvy Control Editor 

• PowerPlant text traits and menu command support 

• Complete AIFF sound file disassembly template 

• Big-, little-, and even mixed-endian template parsing 

• Auto-backup during file saves; folder attribute editing 

• Ships with PowerPC native, fat, and 68K versions 


New 

in 

2 . 0 : 


Requires System 7.0 or greater, 
1.5MB RAM, CD-ROM 


Standard price: $256 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 


Fully supported; it’s easier, faster, and more productive than ResEdit 
Safer memory-based, not disk-file-based, design and operation 
All file information and common commands in one easy-to-use window 
Compares resource files, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 
Makes global resource ID or type changes easily and safely 
Builds resource files from simple Rez-like scripts 
Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 
Hot-linking Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

Full integrated support for editing color dialogs and menus 
Try out balloons, Mctb’s, lists and popups, even create C source code 
Integrated single-window Hex/Code Editor, with patching, searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 


Payment: Check, PO's, or Visa/MC 
Taxes: Colorado customers only 


Extras (call, fax, or email us): 


ojAuiao LOA, Ui email 110/ 

COD, FedEx, UPS Blue/Red, 


International Shipping 


MATHEMiESTHETICS, INC. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 


resorcerer@ma themaesthetics. com 


To order by credit card, or to get the latest news, bug fixes, updates, and apprentices, visit our website... 


www.mathemaesthetics.com 
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by Eric Gundnim <editor_ementiis@mactech.com> 


WWDC, What Apple Has Been Up To 

WWDC is over, and I’ve just spent a full week listening to 
the official At)plc message. Many weeks may have passed by the 
time you read this article, but my mind is still hashing out the 
things I heard just a few days ago. 

I must admit, I attended WWDC 1998 with pretty low 
expectations. Last year attendees had Rhapsody fenced on them 
as the only possible future for Macintosh development. This year 
was very different; Apple listened to developers and offered us 
several options for our future development. I am pleased with 
how well Apple handled the conference. 

You may recall I wrote those same words immediately 
following last year’s WWDC. As I was preparing this column, 1 
thought rd review what 1 wrote last year. I was quite surprised 
to find that the opening paragraphs of last year’s column so 
accurately reflected my feelings alxnit this year’s WWDC. 

Eveiy year developers come away from WWDC excited 
about Apple’s new .strategies and technologies. Why should this 
WWDC be any different? Tliis is the third year in a row that 
Apple has given us a whole new operating system strategy. So 
what’s different about this year’s conference? 

Mac OS X, A Peak at the Future 

By now you’ve probably read all about Apple’s new OS 
strategy. Rather than give us yet another OS, Apple has mixed 
the l)esi tec:hnologies of Mac OS, Rhapsody, Java and even a 
little of Copland. I am much more comfortable with these 
evolutionary changes than with last years OS revolution. 

In a nutshell, Apple is offering a way for existing applications 
to live side-by-side with Yellow Box applications running on the 
Rhapsody Kernel. Similarly, Java and BSD Unix programs also 
should work in Mac OS X. F.xLsting Mac OS software will mn in a 
Blue Box without any of the Rhapsody Kernel benefits. 'I’o be an 
equal player in the Rhapsody world, existing applications musl be 
recompiled to work with the Carbon Toollx)x, a subset of the 
existing Mac Toolbox with some additions. Because Carbon is 
only a subset, some additional coding will be reejuired for most 
applications, llie work .should be minimal; much like the 
transition from 68K to PowerPC, 'fhe benefits of protected address 
spaces alone will likely save developers more time tracing 
memory errors than it will take us to rewrite the portions of our 
applications that rely on problematic Al^ls. 

Apple will not release Carbon until sometime next year, but 
most of the necessary APIs are available today for applications 
mnning under Mac OS 7.5.5 and later. Developers can clean up 
their af)plicalions now and the applications should run in Mac 
OS X without further changes. The details are available from 
Apple’s web site, and probably will appear in a future MacTech 
article. From what I’ve reviewed of the changes, most represent 


removing reliance on obsolete Al^ls (such as those superseded 
by System 7 improvements) and failed technologies (such as 
PowerTalk). Developers today can start preparing their 
applications to take full advantage of Mac OS X, and they will 
get cleaner running applications as a bonus. 

Tlie developers tliat have the greatest challenge are those who 
provide the extensions that we use to personalize our computers. As 
of WWDC there was no equivalent to the airrent extensioas 
mechanism. lastead, we cun extend .some l)ehavlors of Mac OS X 
using the Appearance Manager, drivers and faceless background 
applic^ations. These should cover the mitjority of what programmers 
do uxkiy willi extensions, and they are more stable mechanisms 
than the trap patches we live with now. However, lliese new 
mechanisms are not quite as flexible as patching traps, making it a 
bit more difficult for developers to rekrase their creativity on the Mac 
OS. As I left tlie conference, there wits a gcxxJ chance that the Apple 
engineers, together with some experienced extensioas developers 
were going to develop a clean, .safe mechani.sm to let us hook in 
and provide new, unirnagined extensions. 1 wish them luck. 

A Future For Yellow Box? 

The reasons to build in Yellow Box are not quite so 
compelling any more. Apple did not include Yellow Box in any of 
their keynote pre.sentations, making many develojxrs think tlie 
technology was canceled. However, Apple claims it is alive and 
well, and tliat Yellow lk)x is a .strong environment for building new 
and multi-platform applic'ations. Tliis suggests to me tliat Apple 
might want to migrate developers to Yellow Box as the ftiture 
Toollxix of Mac OS development, but Apple did not make that 
me.ssage very clear. Com|X)und that with Apple’s .siaiemenl liiai 
Rhapsody for Intel will not lie revised lieyond version 1.0, and the 
future of Yellow Box Ixcomes even le.ss clear. 

Maybe Apple is playing a game of wait-and-see: if enough 
products start to take advantage of Yellow Box, Apple will 
continue its development. On the other hand, our industry is 
pouring a lot of resources into making Java the multi-platform 
development environment of choice. With Apple’s directing most 
resources to Mac OS technologies and substantial resources to 
Java, Yellow Box may not liave such a .strong future. If Apple can 
finally catch up their Java to the .same version as the rest of the 
industry, Java will likely become the preferred environment for 
new development. While we wait to .see how this shakes out in 
the next year, we can concentrate on .some very interesting new 
Mac OS teclinologies just around the corner. 

Extending Our Current OS 

Apple appears to be listening to developers like never 
before. They heard our complaints about the forced transition to 
Yellow Box and gave us Carbon. Apparently they also heard our 
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Your softwai’c is your baby - and you want to look 
after it. You created it, you developed it, you saw 
it right thi’ough to the moment it was ready for 
market. Now protect it. 50% of business software 
is stolen; $11 billion of developers’ income is lost 
to piracy.* Is your software a statistic? 


All over the world, more developers are protecting 
against piracy. I’hey re protecting more products, 
on more platforms, with more security ~ and selling 
more as a result. And more of these developers 
are protecting with MacHAvSP. 




MacHASP — The Professional 
Software Protection System 

■ Fully licensed ADB device 

■ Unequalled security 

■ Unparalleled flexibility 

■ Genuine ease-of-use and ^ ^^ 

transparency 

■ Supports System 6.05 and up, including 
System 8.1 

■ ISO 9002 quality and reliability 


To see why 25,000 developers worldwide 

-ii„i i i Jg protect with Aladdin, call and 

order your MacHASP Developer’s Kit now! 


HASP Protects Mere 


North America Aladdin Knowledge Systems Inc. 800 223-4277.212 564-5678, Fax: 212 564-5377. Kmall: hasp.siiles@us.aks.coni 
Int'l Office Aladdin Knowledge Systems Ltd. . 972 3 656-2222. Fax; +972 3 537-5796, Email hasp salcs@aks.com 

Germany Aladdin Knowledge Systems Gmbh & Co. KG +49 89 89 42 21 0. Fax; 1 49 89 89 42 21-40. Email; iiifo@aladdin dr 

UK Aladdin Knowledge Systems UK Ltd. +^4 1753 622266, Fax +44 1753 622262. Email sah 5 @aklfl.c 0 .uk 

Japan Aladdin Japan Co., Ltd. <81 426 60 7191. Fax: +81426 60-7194. Email saies@aladdin co jp 

France Aladdin France SA +33 1 41-37-70-30. Fax +33 1 41-57-70-39. Email: mfo@aIaddm.fr 

Benelux Aladdin Software Security Benelux B.V. +31 24 648-8444. Fax i' 3 l 24 645-1981, Fimail saies@aladdmjil 

Russia Aladdin Software Security R.D. Ltd. 1 7 095 9234)588. Fax; +? 095 928-6781. Email aladdtn@aladdin msk m 


The Professional’s Choice 


McicHASPI Protects 


Software 


■ Australia ContaO 03 98965685 ■ China (Beijng) FsiIM) 010 ft?fi67389 (Hong Kong) Hastings 02 5484C29 (Shenahen) Hastings 0/55 2328741 ■ Cxech Atlas 02 766085 ■ Denmark Serendsen 039 577318 ■ Egypt ZemeWem 02 3604632 ■ Finland 0 Systems 09 8703520 

■ Greece Unlbfain 01 6/56320 ■ India Soiulwn Ot 1 2148254 ■ Italy Partner Data 02 26147380 ■ Korea Uae-A 02 8484481 ■ Mexico .SiSofl 091 80055283 ■ Poland Systherm 061 4802/3 ■ Portugal Futwmato 0l 4116269 ■ Romania Ro Inlcraclive 064 140383 

■ Singapore im 065 5666788 b South Africa DLfi Roux 011 8864704 b Spain PC Hardware 03 4493193 B Sweden Kofdah 45.5 307 300 B Switzerland Opag OGI 7169222 b Taiwan leco 02 55598/6 B Turkey Mtkroheta 0312 4670635 B Yugoslavia Asys 021 623920 
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reciuests for certain Mac OS-based tcclinologies; they have given 
us services weVe been requesting for years. 

One such technology is the new Window Manager including 
OS support for floating windows. Instead of developers having to 
muck around with an application’s window list or other private OS 
data stnictures, Apf)le is giving us an API to identify which layer 
our windows reside in and the OS will manage window ordering 
and appearance for us. 'llie new Window Manager contains many 
more useful services reminiscent of Copland. 

Navigation Seivices is another new technology developers can 
Ix^gin using texlay. Nav Seivices is a non-mcxJal and extensible 
ie|')lacement for the dec repit Standard File package. I’ve not look 
closely enougli at the APIs, but I’m hoping that it also is replaceable. 
In the past developers have offered significant improvements on 
Suindard File. I’d hate for Apple to cut out their market and eliminate 
tlie Ix^nefits of llieir prodiicis. As a iLser I want to chcx)vSe tlie file 
navigation interface tliat works lx*st for me. With Nav Services Apple 
has defined a standard interface. Now they should let anyone plug 
in an alternative if that is what the user wants. 

Subwoofer is back in the form of UKLAccess. With a veiy 
few simple API calls, any application now can do FTl^ and 
HTTP uploads and downloads. Imagine that your product can 
post user registration information automatically using a few 
simple calls. Best of all, the IJRLAccess technology is fully 
extensible; developers can write new modules for their favorite 
protocols and ju.st drop them in. Hopefully Apple will also 
extend the list of protocols. Fd very much like to see at least 
SM'l’P Send support in the initial relea.se. 

After a very long .sabbatical, the keychain is back. No 
longer will users have to remember all those passwords to 
AppleShare servers, FTP .servers, or any other services 
requiring passwords. With a few simple API calls, we 
developers can look in the keychain for the pa.s.sword 
information instead of asking the user. 'I'he keychain can store 
anything the developer wants to put in it. As presented at the 
conference, the keychain has a long way to go to become a 
mature service, but Fd rather have a little bit now, than wait 
another several years for Apple to reimplement all of 
PowerTalk. What’s missing: the keychain does not yet offer a 
standard, .secure passphra.se dialog to be used by all 
applications, nor does the keychain offer any protections 
against one application snooping the data in.serted by another. 
In time I expect Apple with plug these holes. 

In an effort to migrate the Mac from AppleTalk to TCP/IP, Apple 
is providing system-level .servicL‘s for registering and locating 
resources on any network, including TCP/IP. Tliis tec:hnology has 
Ixxm a long time coming. Apple wall be providing a simple API for 
applications to register their .services on the nenvork, and for otlier 
applic'ations to find them. S(X)n asers will lx able to tnily browse 
the Internet to see what .services are offered instead of having to 
know the magic URL to get .somewhere. 

These are just a few of the new services becoming available 
in the next few releases of Mac OS. Apple pre.sented .several others 
I don’t have .space to list. You can bei MacTech will lx covering 
them in articles as fast as we can get the details out of Apple. 


A Blemished Apple 

'Ihe one technology tliat liad developers in the biggest uproar 
was Apple’s claim to be removing support for OpenTransport 
Stieams from Mac: OS X. This was announced even while Apple 
pre.sented one of tlie most clc^ar and useful sessions ever on using 
OT Streams. Apple publicly aigues that OT .stre^ams have not been 
widely adopted, and they claim they can provide sufficient 
hinaionality in Mac OS X using the RSD Networking Stock. (In case 
you don’t know the history, XTI Streams, on which OT is based, 
were developed more tlian ten years ago to cleanly pnivide 
extensible networking that could not be had with the BSD Stack.) 

Unfortunately the Apple Rhap.sody networking group is in 
a tough spot. One choice they have is to move Rhap.sody to 
Streams, but then they have to rewrite all their Rhap.sody-ba.sed 
networking services such as Netinfo, Telnet, FTP and others. The 
other choice is to try to shim the OpenTran.s|X)rt client APIs onto 
the BSD .Stack. This later choice eliminates the API calls u.scd by 
products which provide low-level networks services .such as PPP, 
secure (encrypted) networking, multi-homing, software routing 
and others. Rhap.sody provides .some of the.se .services, but third 
parties will not be able to replace them with alternative seivices. 
(Such replacement of the.se .services reejuires recompiling the OS 
kernel; we can’t have u.sers doing that.) 

Developers made very compelling arguments for Apple to 
stick with streams and not step backwards to the days when 
every application contained its own networking stack. 
Unfortunately for Apple that means they may have to rewrite 
.some of their own networked Rliapsody applications, becau.se 
tho.se applications did not u.se the public APIs as the rest of us 
must. Td rather see Apple clean up their own me.ss than force 
developers into it. Til even accept a .significant delay in the 
relea.se of all tho.se Rhap.sody-ba.sed services. 20 million Mac OS 
u.sers won’t mind waiting an extra six months for Netinfo and 
the like; it’s the core OS we want. Apple promi.sed they would 
revisit this decision. I hope they carefully consider how their 
choice will affect the next ten years of Macintosh networking; 
getting this far has Ixen pretty painful. 

In nearly all other areas Apple has demoastrated their 
willingness to listen to develofxrs, providing us with some very 
compelling technologies I and others are anxious to take 
advantage of. Wliere networking is concerned, A[>ple .seems to 
have made their decisions without having accurate infonnation 
about the importance of tins technology to developers and our 
u.sers; we have now provided them with that information. I am 
confident that once Apple reconsiders their decision to remove 
streams support that they will not ignore such an important core 
OS technology. In fact, I encourage developers interested in 
networking to look at Apple’s newly relea.sed OpenTransport 
documentation: Inside Macintosh: Networking with Open 
'Transport and OT Advanced Client Programming. 'These two 
volumes represent significant improvements over what was 
previously available, allowing developers to write serious 
network-sawy code with a lot le.ss effort. Apple has given us the 
tools to make the Mac the premier platfonn on the Internet; it’s 
up to us developers to write the code to keep it tliere. Ei 
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GETTIlUC 

STARTED 


hy Dave Mark and Dan Parks Sydow 


Using the List Manager 


Before we get into this month's 
column, I would like to take a 
moment to introduce my friend 
and collaborator, Dan Sydotv. You 
might know Dan from his many 
Mac programming books. Over 
the coming months, Dan and 1 
will work together to produce the 
monthly Getting Started column. 

/ think Dan will help broaden the 
perspective of the column. I hope 
you enjoy this collaboration as 
much as we do! 

--Dave Mark 


How a Mac program 
handles lists 


In recent columns, youVe learned the 
very basics of Mac programming, including 
how to write event-based applications that 
make use of windows. Ui.st month we 
moved Ixfyond the basics to l(X)k at dialog 
fillers. Now it’s time to continue on die palli 
of covering slightly more involved topics. 
'Iliis month we study the list. Including a list 
in a window is a common practice in Mac- 
programs. The list is a powerful tool that 
allows the user to easily make his or her 
wishes known to the program. And while 
implementing a list is a little more complex 
than, say, adding a button to a dialog box, 
in this column you’ll see lliat the List 
Manager provides a big assist. 


Tilt Lis'!* Manager 

The List Manager is the part of the Macintosh Toolbox that 
allows you to create and manage scrollable lists. Such a list 
allows users to select an item from a group of items, llie vast 
majority of Macintosh applications make use of the List Manager, 
albeit indirectly. The standard Open dialog box commcm to 
programs that allow the user to choose a file to open holds a list 
created and governed by the List Manager. Figure 1 shows the 
result of a call to the 'Ibollx)x function StandardGetFile(). 


[o BootPhve ^) 




Apps-Games 

1 

Apps-Graphics 


1^ Apps-Sound 


CJ Apps-Word Processing 


Apple Extras 


Cl Assistants 

▼ 


^ BootDrive 
[ Fiect ] 

I Pesictop j 


[ Cancel j 




Figure 1. The List Manager, as used by StandardCeLFileQ. 


The dialog box shown in Figure 1 is the product of calls to 
List Manager functions that display the list of files to open, and 
Dialog Manager functions that create the dialog box that houses 
the list. StandardGetFileO shields all these calls from you, the 
programmer. In this article we’ll dig a little deeper and see how 
to make use of the List Manager directly to place a list in a 
window of our own creation. 


Dan Parks Sydow is the author of over a dozen programming books, including foundations of Mac Programming^ by IDG 
Books. Dan’s lending a hand on this Getting Started article. 
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PictLister 

Tills month’s program is PictLister — a program designed to 
showcase the List Manager. PictLister lets you create a window 
listing all the PICT resources available to your program. The 
available resources include those in the application’s own 
resource fork, as well as those present in any resource files tliat 
the System has open. An example of the latter is the System file’s 
own resource fork, which is always open and accessible by 
applications. The window on the left side of Figure 2 includes a 
list that shows the PlCf resources found by my copy of PictLister. 



Linked 
Teddy Bear 
Car 

World Map 

Moon 

Sun 

Light Bulb 
Juggler 
Turnip 
Oz 

Teievision 

<Unnamed> 

<Unnamed> 

<Unnamed> 


Party Hat 



Figure 2. A PictLister window. 


To demonstrate how user-interaction with a list takes place, 
double-clicking on the name of a PICT re.source causes PictLister 
to display the selected picture in its own window. Figure 2 shows 
the picture-displaying window that appears when the Party Hats 
item is selected in from the list in the Picture Li.st window. 

Creating the PictLister Rfjsovrcks 
Start by creating a folder named PictLister inside your 
development folder. Fire up ResEdit and create a file named 
PictLister.rsrc inside your PictLister folder. 

PictLister needs one menu bar resource and three menu 
resources in order to display its menu bar. Begin by creating an 
MBAK resource with an ID of 128. The MBAR should list three 
MENU resource IDs: 128, 129, and 130. Create three MENU 
resources according to the specifications in Fig:ure 3. Be sure to 
include a separator line as the third item in the File menu. 


£} 


CNUs from PfctUsterjrsrc ; 






i 

1 

I3IFI 

\ ] 

E39 

1 



About PIctUster. | 


Newlist XN 


1 : 

Undo 

XZ 

1 

1 





Qose 


\ \ 

Cut 

XX 

1 

i 





Quit «Q 


1 1 

Copy 

xc 

1 




j 



Paste 

XV 

» 




i 

i 


1 i 

[ i 

Gear 


1 

1 

1 

i 







128 

129 


ISO 



Figure 3. The three MENU resources. 


You’ll need to create two WIND resources. The first WIND 
has an ID of 128, and defines the properties of the list window. 
Create this WIND based on the specifK:ations shown in Figure 4. 
Note that the Close box check lx)x is unchecked. Because the list 
window is the heart of the PictLister program, it doesn’t include a 
close box — it remains on screen until the user ejuits. 



Figure 4, The list window WIND resource 


Any time a picture is displayed in PictLister, it’s displayed in the 
same window — a window based on a WIND resource with an ID 
of 129. The picture window won’t be resizable, .so after you create 
this WIND, click on the icon .second fnim the left in the row of small 
window icons located at the top of tlie WIND (it doesn’t include a 
size box). The picaire window is closeable, so check the Close box 
check box. Set the location and size of the window to any reasonable 
values — PiclLLsler will lx* resizing tlie window as the program mns. 

Now add any number of PICT resources to the resource file. 
Go into the scrapbook (or your favorite graphics application) and 
use Copy and Paste to create a series of PICT resources in the 
resource file. When finished, double-click on the icon labeled 
PICT in the PictLister.rsrc file to open a window that displays c^ch 
picture. One-by-one, click on a PICT resource, select Get 
Resource Info from the Resource menu, type in a name, and check 
tlie Purgeable check box. That last step gives the system to free 
up the memory the picture ocrupies when the picture data has 
been loaded but isn’t in use. Figure 5 shows the Get Resource 
Info window for my first PICT resource. 


H Pier 128 from PiitLi$ter.rsrt^^^^gB 


Type: 

pia 

Size: 5194 

ID: 

128 


Name: 

Party Hat 


Ownertype 


Owner ID: 

Sub ID: 

Attributes: 

□ System Heap □ Locked □ Preload 

B Purgeable □ Protected □Compressed 


Figure 5. Get Resource Info for my first PICT resource. 
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It’s imporUint to name your PICT resources, since Picti.ister 
uses the PICTs name to represent the PICT in a PiciLisier 
window (refer back to Figure 2 to see an example). 

Creating the PiciLister Project 
If you haven’t saved the resource file and quit ResEdit, do so 
now. Launch CodeWarrior and create a new project based on the 
MacOS:C_C++:MacOS T(x:)lbox:MacOS Toollxix 68Kstationary. 
Uncheck the Create Folder check box. Name tlic f)rojcci 
PiciLisier.mcp and place it in your PictLister folder. Remove 
SillyBalls.c and SillyBalls.rsrc from ihc project; we will not be 
using these files in this project. From the Finder, drag and drop 
your PicitLister.rsrc file into the project window. Click the OK 
button if you see ihe Add Files dialog box. Our project won’t be 
using any of the standard ANSI libraries, so you can remove a 
little clutter by dragging the ANSI Libraries folder from the project 
window lo your desktop’s Trash can. 

Choose New from the File menu to create a new source ccxle 
window. Save it witli the name PictLister.c, then select Add Window 
from the Project menu to add this new file to your project. Now 
your project window should kxik similar to mine — the one 
pictured in Figure 6. 




Segment? j 
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■ . . 
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68K Debu^MacOS Toolfe^^| 

'3 




B] 







0^ Sources 
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5 files 

7ZK 
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Figure 6. PictLister project window. 


Now it’s time to type in the PictLister code in the PictLister.c 
file. You can do as you read the through the following .source 
code walk-through, or you can greatly reduce your efforts by 
downloading the whole project from MacTech’s ftp site 
<ftp://ftp.mactech.com/src/>. 


//define 

kMoveToFront 

(WindowPtr)-IL 

//define 

kListDefProc 

0 

//define 

kDrawIt 

true 

jdefine 

kHasGrow 

true 

//define 

kHasHScroll 

true 

//define 

kHasVScroll 

true 

//define 

kFindNext 

true 

//define 

kMinWindWidth 

150 

//define 

kMinWindHeight 

60 

//define 

kWindOrigWidth 

200 

//define 

kWindOrigHoighl 

255 

//define 

kBaseResID 

128 

//define 

kListWindID 

kBaseResID 

//define 

kPictureWindID 

kBaseResID11 

//define 

mApple 

kBaseResID 

//define 

lAbout 

1 

//define 

mFile 

kBaseResID+1 

//define 

iQuit 

1 


The global variable gDone .serves its usual role, indicating 
when it’s time to drop out of the main event loop. There will be 
just one list window open at all times, so it makes sense to 
declare the global WindowPtr variable gListWindow to keep track 
of it. The ListHandle variable gListHandle makes it easy to access 
the list window’s list at any time. A similar situation exi.sts for the 
picture window: gPictWindow lets us access the picture window, 
while gCurrentPicture provides a means of working with the 
window’s picture. 


globals ♦«**’»**«*******«**7 


Boolean 
WindowPtr 
Li r. t Handle 
WindowPtr 
Picllandie 


gDone; 

gLislWindow = NULL; 
gListHandle = NULL; 
gPictWindow = NULL: 
gCurrentPicture “ NULL; 


As usual, we provide a function prototype for each function 
in the .source file. 

r*^*^************** functions ****************^/ 

void ToolBoxInit ( void ); 

void MenuBarInit ( void ); 

void CreatePictureWindow( void ); 

void CreateListWindow( void ); 

void EventLoop( void ); 

voidDoEvent( EventRecord *eventPtr ); 

void HandleMouseDownt EventRecord *eventPtr ); 

void DoContentClick( EventRecord ‘eventPtr, 

WindowPtr window ); 
void SetWindowPicture( void ); 

voidDoGrow( EventRecord *eventPtr, WindowPtr window ); 
void DoUpdateC EventRecord *GveiitPtr ); 

void DoActivate( WindowPtr window, Boolean becomingActive ); 
void HandleMenuChoice( long menuChoice ); 
void liandleAppleChoiceC short item ): 
void HandieFiieChoice( short item ); 


Walking Through the Source Code 
PictLister makes u.se of ctxie that’s been discussed in recent 
columns, so our explanation of tilings like the event kxip and 
window creation is light. Instead, the focus is on list-related code. 

PictLister starts off with a bunch of #defines, some familiar, 
some not. As usual, you’ll see what they do in context. 

constants 

//define kSleep 7 


The main() routine initializes the 'foolbox, sets up the menu 
bar, opens a couple of windows, tlien enters the main event loop. 


void main( void ) 

( 

ToolBoxInit0; 
MenuBarInit0; 

CreatePictureWindowO ; 
CreateListWindowO ; 
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EventLoopO ; 

1 


ToolboxInItO does its usual thing. 

r**********”*^”**T(K)llk)xInit 

void ToolBoxTnit ( void ) 

I 

InitCraf( &qd.thePort ); 
InitFontsO ; 

InitWindowsO ; 

InitMenusO ; 

TFJnitO ; 

TnitDialogr,( nil ); 

InitCursor0: 

) 


MenuBarInitO is no different than previous versions: it loads 
the MBAR, adds the normal resources to the ll menu, and draws 
the menu bar. 

/**“•**“***•*”•*•* MenuBarInil 

void MenuBarliiil ( void ) 

I 

Handle menuBar; 

MenuHandle menu: 

menuBar = GetNewMBar( kBaseResID ): 

SelMcnuRar( menuBar ): 

menu = GetMenuHandle( mApple ); 

AppendResMenut menu. ‘DRVR’ ); 

DrawMenuBar0; 

) 


CreatePictureWindowO creates a window that’s to be used to 
display the picture that the user evenuially will choose from the 
not-yet-opened list window. We’ll create the window and assign 
it to the global variable gPictWindow here, but we won’t display 
it just yet. You should have unchecked tlie Initially visible check 
lx)x in WIND resource 129, but just in case you didn’t the call to 
HideWindowO hides the window. We’ll display it only after the 
user choexses a li.st item in the list window. 

/***************• CreatcPicturcWindow 

void CreatePictureWindow( void ) 

( 

gPictWindow = GetNewWindow( kPictureWindlD, nil. 

kMoveToFronl ); 

if ( gPictWindow “ nil ) 

( 

SysBeep (10); /* Couldn’t load the WIND resource!!! V 

ExitToShell (): 

) 

HideWindow( gPictWindow ): 

} 


CreateListWindowO creates the program’s one list window 
and assigns it to the global variable gListWindow. 

/*****•****•******* CrcatcListWindow •*••**•••«***•«/ 


void CreateListWindow( void ) 
( 


Rect 

r; 

Rect 

dataBounds; 

Point 

cSize. cindex; 

short 

i. dummy, nuraPicts; 

Handle 

rHandle; 

short 

resID; 


ResType theResTypo: 

Str255 rName; 

gListWindow = GetNewWindow( kListWindID. nil. 

kMoveToFront ); 

if ( gListWindow = nil ) 

( 

SysBeep ( 10 ); /* Couldn’t load the WIND re.source!!! V 

ExitToShell0: 

) 

The font used in the display of list items is based on the 
current graphics port font. T’he call to TextFont() ensures that the 
list is drawn using the system font (which may be either Charcoal 
or Chicago, depending on the user’s System Font setting in the 
Appearance control panel). Precede the call to TextFont() with a 
call to SetPortO so that the text-setting affects the list window. 

SetPort( gListWindow ): 

TextFont( systeraFont ); 

Next, we prepare to create our list. The rectangle 
dataBounds specifies the initial setup of the list. In this case, 
we’re specifying a list 1 column wide and 0 rows deep. We’ll 
add rows to the list a little later. 

SetRect( &dataBounds. 0. 0. 1, 0 ); 

cSize specifies the size, in pixels, of each cell in the list. By 
pa.ssing (0,0) as the cell size, we ask the List Manager to calculate 
the size for us (based on the eventual contents of the cell). 

SetPt( StcSize, 0, 0 ); 

Finally, r is a Rect that specifies the Ix)unds of the li.st. Because 
the scroll bars are drawn outside this area, we allow room for tliem 
to fit between the list and the window right and bottom sides. The 
values of the constants kWindOrigWidth and kWindOrigHeight come 
from the values used in the list window WIND re.source. 

SetRect (&r, 0, 0, kWindOrigWidth-15, kWindOrigHeight-15); 

The list is created via a call to LNew(). LNew() accepts a list 
definition procedure tliat specifies some aspects of the list. Using 
a value of 0 (which we defined kListDefProc to be) specifies the 
u.se of the default list definition. 'I’he Boolean value kDrawlt tells 
the List Manager to enable automatic drawing mode — a mode 
that has the List Manager automatically redraw the list whenever 
a change is made to it. The Boolean variables kHasGrow, 
kHasHScroll, and kHasHScroll tell the List Manager to add two 
scroll bars and a grow box to the list. 

gListHandle = LNew( &r. &dataBounds. cSize, kListDefProc, 
gListWindow, kUrawit, kHasGrow, 
kHasHScroll. kHasVScroll ); 

LNew() returns a handle to a ListRec, the data stnicuire 
representing the list. We store this handle in the global variable 
gListHandle to be used throughout the program. 

'Ihe selFlags field of a ListRec lets you specify how the list 
reacts to clicks in tlie list. We’ll use the flag lOnlyOne to tell the List 
Manager that only one item at a time can be highlighted in tliis list. 

(*‘gListHandle).selFlags = lOnlyOne; 
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'1‘his next chunk of code adds ilic rows to the list. We’ll add 
one row to the list for every available PICT resource. 

niitiiPicis = CountResources( ‘PICT* ); 

for ( i - 0; i < numPict.*:; 1++ ) 

I 

For each resource, retrieve the resource handle using 
GetIndResourceO, then call GetReslnfo() to retrieve the resource 
name, if it exists. 

rHandle “ GetIndResource( ‘PICT*, i + 1 ): 

GGtResInfo( rHandle, &rcsll). fidheResType, rName ): 

LAddRowO adds one row to the list specified by 
gListHandle. clndex is set to the cell in the first (and only) 
column and in the ith row. 

dummy = LAddRow( 1. i. gListHandle ); 

SetPt( &clndex. 0. i ); 


Next, tlie data is added to the cell specified by clndex. If the 
resource is not named, the string “<Unnamed>” is used instead. 

if ( rNamef 0 ] > 0 ) 

LAddToCelH &(rName[l]), rNametOj, clndex, gListHandle ); 
else 

LAddToCelK “<Unnamed>”, 10, clndex, gListHandle ); 


Next, the window is made visible, and LSetDrawingMode() is 
called to enable drawing in the list. This doesn’t mean that the 
list will be drawn at this point. Instead, tlie next time the List 
Manager is asked to draw the list (perhaps via a call to 
LUpdateO), it will be able to. 

ShowWindow( gListWindow ); 

LSetDrawingMode( true, gListHandle ): 

I 


EventLoopO looks and behaves as it has in previous 
articles — there are no surprises here. 

pventlxx)p *****************^/ 

void EventLoop( void ) 

I 

EventRecord event; 

gDone “ false; 

while ( gDone = false ) 

{ 

if ( Wa UNcxlEverit( everyEvent, &evGnt. kSleep, NULL ) ) 
DoEvcnL( &event ); 


) 


DoEventO dispatches tlie Sfx:eified event. Again, this routine 
remains as we’ve developed it in recent articles. 

DoEvenl *«««*««*»**««*7 

voidDoEvent( EventRecord *eventPtr ) 

( 

char theChar; 

Boolean becomingActive: 

.switch ( cvGntPtr->what ) 

I 
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case mouseOown: 

HandleMouseDown( eventPtr ): 
break; 

case keyDown: 
case auloKcy: 

theChar = eventPtr*>inessage & charCodeMask: 
if ( (eventPtr >modifiers & cmdKey) != 0 ) 
HandleMenuChoice( MenuKey( theChar ) ): 
break; 

case updateEvt: 

DoUpdate( eventPtr ); 
break; 

case activateEvt: 

becomingAcLive = ( (eventPtr->modifiers & activeFlag) 
= activeFlag ); 

DoActivate((WindowPL r)eventPtr->message. 
becomingActive ); 

break; 

1 

} 


Most of HandleMouseDownO should look familiar to you. 

HandlcMouscDown *****************/ 

void lIandlcMouseDown( EventRecord *eventPtr ) 

I 

WindowPtr window; 
short thePart; 

long menuChoice; 

ihePart = FindWindow( eventPtr->where, ^window ); 

switch ( ihePart ) 

{ 

case inMenuBar: 

menuChoice = MenuSelect( eventPtr->where ); 
HandleMenuChoice( menuChoice ); 
break; 

case inSysWindow : 

SysieiiiClIck( eventPtr, window ); 
break; 

case inContent: 

DoContentClick( eventPtr, window ); 
break; 

case InGrow: 

DoGrow( eventPtr, window ); 
break; 

case inDrag : 

DragWindow(window, eventPtr->where, 

&qd.screonRits.bounds ); 

break; 

'llie one exception is the call to HideWindow() when the 
mouse is clicked in the go away box of the picltirc window. 
Rather than destroy the window when the user opts to close it, 
PictLister simply hides it. As you’ll see ahead, when the user 
double-clicks on an item in the list window list, we’ll again show 
the now-hidden window. PictLister doesn’t allow the list window 
to be closed, so we won’t include any list window closing code 
here (doing so would lx? as easy as omitting the check to see 
which window was being closed). 

case inGoAway: 

if ( TrackGoAway( window. eventPtr->whGrc ) ) 

( 

if ( window = gPictWindow ) 

HideWindow( window ); 

I 

break; 

1 

) 

DoContentClickO is called when the mouse is clicked in 
the specified window’s content region. DoContentClickO begins 


by checking to see if the clicked-on window is the fronimost 
window. If it’s not, SelectWindow() is called to bring the 
window to the front. 

/--»*»****»*»»* DoContcntClick 

void DoContentClick( EventRecord ‘eventPtr, WindowPtr window ) 

I 

if ( window != FrontWindowO ) 

{ 

SelectWindowC window ); 

) 


If the click was in the frontmost window and the window 
is a list window, we’ll convert the current mouse coordinates 
(which are in global coordinates) to the window’s local 
coordinate .system. 

else if ( window = gListWindow ) 

( 

SetPortC window ); 

GlobalToLocal( &(eventPtr >where) ); 

Next, a call to LCIick() is made. This routine handles all 
types of clicks, from clicks in the scroll bars to clicks in the 
list cells. LCIickO returns true if a double-click occurs. In that 
case, we’ll invoke the application-defined routine 
SetWindowPictO to determine which picture is to be displayed 
in the picture window. 

if ( t.Click( eventPtr*>where. eventPtr >modifiers, 
gListHandle ) ) 

SetWindowPicLureO ; 

) 

) 


SetWindowPictureO performs a numlx*r of tasks — a handful 
of local variables help out here. 

/******-******^** SetWindowPictWindow 

void SetWindowPictureC void ) 

( 

Cell ceil; 

Handle rHandle; 

Rect r; 

short resID; 

ResType theResType; 

Str255 rName; 
short pictWldth; 
short pictlleighL; 

The first chore is to figure out which of the list’s cells is 
selected. We’ll start by setting cell to identify the first cell in tlie list. 

SetPt( &cell. 0. 0 ); 

LGetSelectO staits at cell, then moves through the list until it 
finds a cell that is highlighted. If LGetSelect() finds a highlighted 
cell, it puts the cell’s coordinates in cell and returns true. 

if ( LGetSelectC kFindNext. fitcell. gListHandle ) ) 

( 

If a highlighted cell was found, we’ll first hide the picture 
window to give the appearance that we’re closing the current 
picture window in order to open a new one. 
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Love AppleScript but need an interface? 


FaceSpan, the interface builder for AppleScript, 
dramatically increases the power and usability of your 
scripts. 

Whether you want to create a custom tool palette 
that gives you quick access to your favorite scripts, a 
floating window that ties together the functionality of 
multiple applications or a full-featured AppleScript 
application... 

FaceSpan is the answer. 

''If AppleScript is a hidden jewel in the Mac OS, 
then FaceSpan is its most brilliant exposition." - Howard 
Oakley, 4 1/2 Mice, MacUser UK 

"No scripter's workshop should be without 
FaceSpan." - Tim Warner, 4 Stars, Macworld 



Example of an interface created in FaceSpan. 


To ORDER FaceSpan or for additionae information: 

1-800-322-3772 (USA) 

1-801-226-2984 (Other Countries) 
1-801-226-8438 (Fax) 
sales@facespan.com (E-mail) 

http://www.facespan.com 



Automate 

often-repeated 

tasks. 


Rapidly build 
applications & 
prototypes. 


Customize 

existing 

applications. 


Integrate 

multiple 

applications. 
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your computing 
environment. 


Features new to FaceSpan 3.0 allow you to: 


• Create interfaces that conform to the 
Mac OS 8 look and feel. 

• Utilize new supported display objects 
such as tab panels, disclosure triangles 
and bevel buttons whose functionality is 
built in. 

• Define linkages that hide/show or 
enable/disable window items when 
another item is hilited. 

• Develop hierarchical menus and assign 
command key modifiers directly. 
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New! Expanded 
tool palette! 


• Select applications over which floating windows 
appear. 


• Launch FaceSpan applications up to 5X faster. 


FaceSpan 

A Product of Digital Technology International 


© 1998 Dt};ital TtschnoloRy International. All rights reserved. FaceSpan is a trademark uf Digital Technology IntemationaL AppleScript is a trademark of Apple Computer, !nr., registered in the United States and other countries. 


























































































UideWlndowC gPictWindow ): 

Now we’ll use cell.v to retrieve the appropriate PICT 
resource. Notice that cell is zero-based, while GetlndResource() is 
one-based. We’ll also store a reference to the picture in the global 
variable gCurrentPicture. 

rHandle * GetIndResource( 'PICT*, cell.v + 1 ); 

gCurrentPicture ** (PicHandle)rHandle; 

We’ll be basing the size of the picture window on the size 
of the pic'.ture, so here we store the size of the picture in Rect 
variable r. The local variables pictWidth and pictHeight will help 
out in sizing the window. 

r = (*‘gCurrentPicture).picFrame; 

pictWidth = r.right - r.left; 

pictHeight • r.bottom - r.top; 

Next, a call to GetReslnfo() is made to get the PICT 
resource’s name. We then use that name in a call to SetWTitle() 
to set the picture window’s title. If the PICT was unnamed, we 
simply use the string “<Unnamed>’’ for the window’s title. 

GetReslnfo( rHandle, &reslD. StheResType. rName ): 

if ( rNameI 0 ] > 0 ) 

SetWTitle( gPictWindow, rName ); 

else 

SetWTitle( gPictWindow. “\p<Unnamed>” ); 

Finally, we’re all set to resize the window to match the 
[)iclure’s size, show the hidden window, and then select it so that 
it becomes active (highlighted). 

SizeWindow( gPictWindow. pictWidth, pictHeight. true ); 

ShowWindow( gPictWindow ); 

SelectWindow( gPictWindow ); 

) 

1 


DoGrowO is called when the mouse is clicked in a 
window’s grow box. 

yi*««««*«»M«««M***«**** UotirOW *****************^'*^**^ 

voidDoGrow( EventRecord ‘eventPtr, WindowPtr window ) 

{ 

Rect r; 

Cell cSize; 
long windSizc; 

If the window is a list window, we’ll first establish the 
minimum and maximum size of the window. 

if ( window *= gListWindow ) 

I 

r.top = kMinWindHeight: 
r.bottom = 32/67; 
r.left - kMinWindWidth; 
r.right “ 32767; 

Next, we’ll call GrowWindowQ. If the window was resized, 
we’ll call SizeWindowO to resize the window, then LSize() to let 
the List Manager know that the list has been resized. 


windSize = GrowWindow( window, eventPtr >where, &r ); 

if ( windSize ) 

I 

SetPort( window ); 

EraseRect( &window >portRect ); 

SizeWindowC window. 

LoWord (windSize). 

HiWord(windSize), true ); 

Notice that the scroll bars are not included in the list’s height 
and width. 

LSize( LoWord(windSize) 13, 

HiWord(windSize)-13, gLisiHandle ); 

Next, cSize is set to the current cell size in pixels (including 
both height and width). In its quest for efficiency, the system 
frecjuently rearranges blocks of heap memory as a program ains. 
Here were about to alter data in an object in the heap, so while 
adjusting the cell size we play it safe and loc:k the list data 
stRicmre in memory so that the system can’t move it. 

HLock( (Handle)gListHandle ); 

cSize ^ (‘gListHandle)->cellSize; 

HUnlock( (Handle)gLi.<JtHandle ); 

Though the height of a cell ha.sn’t changed, we’re going to 
make our cell as wide as the window. Note that this won’t always 
be the case (resize an Excel spreadsheet and the cells don’t 
change size). We’ll call LCellSize() to resize all the cells and 
InvalRectO to force an update. 

If you have any doubts about any of these calls, try 
commenting them out and see what happens. 

cSize.h = LoWord( windSize ) 15; 

LCellSize( cSize, gListHandle ); 

XnvalRect( &window->portRect ); 

1 

) 

I 

Back in DoEvent() you .saw that DoUpdate() is called to 
handle an updite event. 

^********************* DoUptlaie *****************^**7 

void DoUpdate( EventRecord ‘cventPtr ) 

( 

WindowPtr window; 

Rect r; 

We’ll retrieve the WindowPtr from the EventRecord. As 
always, we’ll make sure the port is set to the window to update, 
and we’ll sandwich our update proce.ssing code between calls to 
BeginUpdateO and EndUpdate(). 

window = (WindowPtr)(eventPtr->message); 

SetPort( window ); 

Beginllpdate( window ); 

If the window is the list window, we’ll redraw the grow box, 
then call LUpdate{) to let the List Manager update the li.st as 
needed. Simple, eh? 
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Graphically link interface elements to JavaScript variables. Add scripts to the '.nib' file. 
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triple a plus 

Joy Developer 2.0 

by AAA+ Software 

Java-Script Carbon and Yellow Box! 

B Access any C, Objective-C, or Java API from the 
new JavaScript-compliant scripting language. 

B Test your code immediately with the Joy-enhanced 
InterfaceBuilder. 

B Develop full-featured applications in minutes. 

No compiling. No linking. 

B Browse any application's objects and classes at 
runtime and send them messages. 

Joy 2.0 ships in Q3/98 as a FREE upgrade to registered users. 

Prerelease versions are available on request. 

Joy 1.0 received a MacTech Best Tool for New Technologies 

Finalist Award. 

Download and test Joy torJay: 

http://www.aaa-plus.com/joy/ 

Price: $ 399 

Available for Rhapsody PPC, Intel, 

Windows NT/95, and OPENSTER 

Email your order today: 

order@aaa-plus.com 



if ( window gT.lsLWlf»dow ) 

{ 

DrawGrowIcon( window ); 

LUpdateC (**gListHandle) .port->visRgn, gLi.stHandle ); 

I 

If the window is the picture window, we’ll determine the 
size of the picture by l(X)king at the size of picture window’s 
f)orl. Recall lhal in SetWindowPicture() we based the size of the 
picture window on the size of the picture that was to be 
displayed in it. The picture data is referenced by the global 
variable gCurrentPicture, so we can go ahead and call 
DrawPIctureO using gCurrentPicture. 

elfie if ( window — gPicLWindow ) 

{ 

r = gPiclWiiidow->portRect: 

DrawPicture( gCurrentPicture, &r ); 

I 

EndUpdate( window ): 

) 

DoActivateO handles activate events. Since the picture 
window doesn’t need any special activate event processing, all 
we have to do is handle list window activates. 

noActivatc *******************7 

void DoAcLivaleC WindowPtr window. Boolean becomingActive ) 

( 

if ( window ~ gListWindow ) 
f 

if ( becomingActive ) 

LActivate( true, gLisLlIandle ): 


else 

LActivate( false, gListHandle ); 

DrawGrowIcon( window ): 

) 

1 

I’ve save the menu-handling code for last for one reason: at 
this fX)inL we’re home free. The remaining code, starting with 
HandleMenuChoiceO, is all ctxJe that you’ve seen in recent 
columns. HandleMenuChoiceO dispatches a menu selection. Tliis 
(xxle comes from recent columns. 

/••♦*•*•****♦****** HandlcMcnuChoicc ****^********y 

void HandleMenuChoice( long menuChoice ) 

{ 

short menu; 
short item; 

if ( menuChoice != 0 ) 

{ 

menu = HiWord( menuChoice ); 
item = LoWordf menuChoice ); 

switch ( menu ) 

I 

case mApple: 

UandleAppleChoice( item ); 
break: 
case mFile: 

HandleFileChoicef item ); 
break; 

1 

HiliteMonu( 0 ): 

1 

I 


July 1998 • MacTkch 


OirriiNG S'lAR'lliD 


17 































































































switch ( item ) 


3D Graphics Software 
Development Kit 

Everything you need to create stunning graphics on the 
Macintosh® with the industry standard API OpenGL®. 

Create 3D images that use: 

nurbs gouraud shading stenciling 

lighting anti-aliasing texture mapping 

fog Z-Buffering motion blurring 

and more! 

Join the game writers, educators, interactive modelers, CAD 
designers, and scientists who are already using OpenGL. 

Explore the possibilities of 3D programming. 

•Complete with everything you need to learn OpenGL 
•Mac OS, UNIX, MKLinux versions available 
•Hardware acceleration 


Demos available at our web site 



The Industry’s Foundation for High-Performance Graphics 


1.800.577.5505 

www.conix3d.com 


OCoriix Enterprises. Inc. All rights reserved. OpenGL Is a registered trademark of Silicon Graphics. Inc. Macintosh 
is a registered trademark of Apple Computer. Inc All other trademarks are property of Ihoir rospoctive owners. 


HandleAppleChoiceO does what it always does. Create ALRT 
and DLOG ideas, then substitute appropriate alert-opening code 
under the iAbout case label if you want an About box to lie 
displayed in response to the user choosing the About PictLi.ster 
item under the 4 menu. 

/.m,*,.m,**»**** HandlcAppltClioicc ••**••**•****•**7 

void Hand!eAppleChoice( short item ) 

I 

MenuHandle appleMenu: 

Str255 accName: 

short accNumber; 

switch ( item ) 

( 

case iAbout: 

SysBeept 10 ) ; 
break: 
default: 

appleMenu = CetMenuHandle( niApplc ); 

GetMenuItemText( appleMenu. item. accName ); 
accNumber = OpenDeskAcc( accName ); 
break: 

I 

I 

HandleFileChoiceO dispatches selections from the File menu. 
Here we only need to handle one item — Quit. 

HandldilcChoicc 

void HandleFileChoice( short item ) 


( 


case iQuit: 
gDone = true: 
break; 

) 

) 


Running PictLister 

Select Run from the Project menu to run PictLister. The 
first thing you’ll see when you run PictLister is the menu bar, 
featuring the File, and Edit menus, and the Picture Lister 
window. The entire content region of the window (including 
both scroll bars, but not the window’s title bar) is dedicated 
to the window’s list. The items in this list consist of all 
available PICT resources by name. If the resource doesn’t 
have a name, the string <LInnamed> appears. 

Play with the window a bit. Resize it. Notice that there is 
a definite minimum size. Click on an item. Notice that the item 
highlights. Try scrolling the list. Click on an item and drag it 
down or up. If the window is small enough to enable scrolling, 
dragging an item up or down causes the window to auto-scroll 
to the lop or bottom of the list. With very little effort on our 
part (just a call here or there) the List Manager handles the 
scroll bars, clicks in the list, aulo-scrolling, update events, and 
so forth. The List Manager gives you a lot of functionality with 
very little work on your part. 

Double-click on an item in the list. A new window appears 
containing the named PICT. Double-click on another list item 
and it appears that the picture window closes and a new 
picture window holding the newly selected PICT opens. You 
know now that what actually is occurring is that the picture 
window is hidden, resized to the dimensions of the just- 
selected PICT, and then reshown. Closing the picture window 
by clicking on its close box simply hides ihe window. 

Till Next Month 

Next month, we’ll delve deep into windows. Not the “ordinary” 
windows weVe been working with all along, but rather ones of a 
“roll your own” variety. A window definition (WDEF) allows you to 
define a window with any look you want — even a Icxik that 
doesn’t conform to any typical Macintosh window. 

Until next month, look over the PictLister code and read up on 
the List Manager. Check out the List Manager chapter in Inside 
Macintosh: More Macintosh Toolbox for more details. Then 
experiment with ilie PictLister source code. For instance, you 
might want to try adding this feature to the program: Instead 
of using the string <Unnamed> to name unnamed PICT 
resources, try creating a string containing the resource’s 
resource ID, using the string both in the list window and in the 
PICT window’s title. See you next month... 

HI 
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3D Programming with QuickDraw™ 3D 


Getting up-to-speed quickly 
in 3D programming doesn’t 
have to he painful 

Introduction 

Have you noticed how the whole 
worid has gone nutty over 3D grapliics 
lately? Cornpuler-generated imagery was 
already coming on strong before the movie 
Titanic hit, but now you can hardly open a 
magazine or aim on the TV without being 
bombarded willi raylraced logos. “Three- 
D” is no longer just the province of gamers 
and VRML diehards; it’s mainstream. 

If you haven’t considered tapping the 
power of 3D graphics in your own 
programming (or maybe you ruled it out 
because it seemed like such a monumental 
undertaking), now might be a good time to 
rethink the whole issue. As you may know, 
in 1995 Apple unveiled a cutting-edge 
“enabling technology” for 3D programmers 
called QuickDraw 3L), which allows easy 
cross-platform access to a comprehensive 
library of highly optimized 3D routines. You 
no longer have to be a Ph.D. mathematician 
to get 3D graphics to happen. With the 
anival of the latest G3 chipsets, the Mac 
platform is fully capable of handling tlie 
fomiidable computational demands of 3D 
graphics. There’s no longer any reason to 
fear 3D. Ihie way has been paved. 


In this article, we’ll take a look at Apple’s extensive 
QuickDraw 3D API and how you can use it to add that elusive 
third dimension to the already powerful 2D graphic capabilities 
of the Mac. Along the way, we’ll try to simplify (or at least 
demystify) some of the seemingly arcane concepts of 3D 
graphics programming and show how (and why) the QD3D way 
of doing things generally puts you ahead of the game. 

To get the most out of this discussion, you should l)e 
comfortable with object programming idioms (although the code 
will be plain, procedural C) as well as basic 3D concepts, like up, 
down, and sideways. It also wouldn’t hurt for you to have your 
own copy of the latest QuickDraw 3D software developer’s kit 
(SDK), which is available online at Apple’s web site; you’ll need 
it to compile the sample app developed in this article. In keeping 
with the spirit of QuickDraw 3D, I’ll try to hide as many of the 
ugly details of low-level 3D programming from you as possible 
while concentrating on how to get maximum onscreen magic to 
happen with minimum effort. By the time you’ve finished 
reading this article, you should at least have an appreciation for 
the power and scope of QuickDraw 3D, and you’ll be in a 
position (if you so desire) to bootstrap your way up through the 
rest of the vast, complex, awe-in.spiring QD3D API on your own. 

What’s So Great About QD3D? 

Third-party 3D libraries are nothing new. What makes 
QuickDraw 3D unique is that it represents the first lime 
programmers have had support for 3D graphics at the core 
operating system level Mind you, we’re talking about far more 
than just a fancy set of draw routines here. QuickDraw 3D is 
breathtakingly broad in scope and was designed from the ground 
up with developers in mind. Consider some of the design 
features of QuickDraw 3D: 


Kas Thomas <tbo@earthlink.net> ha.s Ix^en a Macinto.sh u.ser since 1984 and has been prograinining in C on the Mac since 1989. 
lie wrote two of the ten most downloaded Photoshop® plug-ins on America On-Line and holds U.S. Patent No. 5,229,768 for a 
high-speed data compression algorithm. His current project involves a QD3D-powered Photoshop® plug-in, code-mtmed Callisto. 
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• Easy access to a comprehensive set of high- and low-level 3r> 
geometries, with support for 20 built-in primitives. 

• A fully cross-platform APT in which device dependencies 
are abstracted out to well-isolated layers. (Porting your 
code to Windows doesn't require a vSquad of Redmond- 
trained consultants.) 

• Inmsparent access to graphics accelerators. (No changes to your 
code are needed to take advantage of QD3r)-compliant lx)ards.) 

• A flexible croSvS-platform 3D file format. 

• An extensible, plug-in rendering architecture. 

• Strong support for texture-mapping using 2D (e.g., PICT) imagery. 

• Built-in pointing and picking support. (User selection of 3D 
objects is easily handled.) 

• A 3D f)ointing-device manager for input devices with more than 
two degrees of freedom. (Tliese guys think ahead, don’t they?) 

• A strongly ol)jecl-oriented API, but 100% accessible in 
procedural C. ('I'hink of it as all the benefits of C++, with 
none of the 3-by-5 cards.) 

• Efficient use of RAM: QuickDraw 3D takes care of various 
aspects of object storage .so that you don’t have to keep large 
arrays around. (Your QD3D-savvy application can run in a 
small partition, even if it creates sizable objects.) 

• Flicker-free realtime rendering courtesy of automatic 
double buffering. 

• Reasonable speed for mo.st applications. 


Some people would quibble with the last statement. 
Hardcore game programmers, for example, aren’t likely to be 
impressed with QD3D’s speed. In my own work. I’ve found that 
objects can be created (or instantiated) at speeds upwards of 
1(X),(X)0 polygons per second on a G3 Mac with no graphics 
accelerator. Displaying objecLs is another matter, of course. 
Doing a 15-degree rotation of a Phong-shaded 13,50()-polygon 
trigrid (rendered at 320 by 240 pixels) can take a full .second, 
using Apple’s interactive software renderer (sans accelerator). 
That’s fast by raylracing standards, but if you’re looking to do 
full-screen realtime animation of com[)lex, photorealistic scenes, 
you’re apt to be disappointed in QD3D (as well as most other 
.software-only solutions). But for many kinds of user interaction, 
QuickDraw 3D’s speed is quite gcxxl. The best way to get a 
handle on this, of course, is lo run .some tests of your own, using 
(for example) the sample app developed later on in this article. 
(Full .source code and executables can be found at the MacTech 
web site <ftp://ftp.mactech.eom/src/14.07/>.) 

What’s Not So Great Akoih QD3D? 

Before signing on for the .steep learning curve as.sociated 
with all 3D programming (QD3D included), you’ll want to 
consider the known drawbacks of QuickDraw 3D, which are few 
in number but pcxentially important, depending on the kind of 
work you intend to do. 
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The first potential drawback, which we’ve just alluded to, is 
speed. For some types of work, QuickDraw 3D simply isn’t fest 
enough. Custom-written special-use code is almost always faster 
than general-purpose libraiy code, but be forewarned: You’ll 
have a tough time improving on some of QD3D’s optimizations. 
(Also, remember that any QuickDraw 3D code you write is 
instantly accelerator-compatible. The real answer to your speed 
problem may, after all, be better hardware, not better software. 
Don’t discount the possibility, too, that someday soon all Apple 
computers may ship with 3D acceleration hardware built-in.) 

Another feature of QuickDraw 3D that’s bound to be a 
disappointment to some is its lack of any kind of built-in 
ray tracing support. (Raytracing is a rendering method that 
achieves [)hotorealistic effects by accounting for reflection and 
refraction.) Many highly realistic effects are possible with 
QD3D’s built-in Phong shading facility, but for true raytracing 
you’ll either need to write your own rendering plug-in or license 
one of the commercial plug-ins available from LightWork Design 
(see <http://www.lightwork.com>). 

The rendering shortfalls of QD3D also extend to lack of 
software-generated transparency effects (available only when a 
QD3D-compatible accelerator is present) and lack of support for 
conslmclive solidgeorrietry or “Boolean”) operations, except 

when an accelerator is f)resent. If you’re already a 3D graphics 
whiz, you may be able to program your own wor*karounds for 


these shortcomings. (CSG, for example, is implemented in the 
POV-Ray freeware raytracing program, for which the complete 
CodeWarrior C source is available on the Internet.) 

One other shortcoming of QuickDraw 3D that may annoy 
some hardcor*e 3D graphics aficionados is the lack of support for 
procedural shaders (a la RenderMan or Lightwave). Creative 
texaire-mapping can overcome this flaw in most cases, but 
texture maps are not true 3D effects: A texture map is actually a 
2D picture “wr-apped” onto a 3D surface. Pr'ocedural or 
volumetr'ic textur-es, by contrast, are tr*uly three-dimensional, in 
the sense that if you saw into a 3D tree branch, you’ll expose 
optically correct 3D veins of lignin throughout the cut, no matter 
how complex the cut or where it occurs. This is hard to fake 
with a wrapped 2D texture. 

The lack of suppoit for procedural textures may seem like 
a minor annoyance, but it also means there is no support for 
hump-mapping, which has lately become a very i) 0 [)ular 
technique for achieving the appearance of complex surface 
geometry without the effort and expense (in terms of RAM and 
computation) of actually modifying the core surface geometiy. 
Again, this is probably a moot point to any but the most 
demanding 3D dilettante, but it helps explain why QD3D is used 
only for “preview mode” operations in commercial 3D pac:kages 
like Inifini-D, Strata Studio Pro, and Lightw'ave 3D. 

Interestingly, procedural shaders have been promised for 
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Mac, go out and touch the world for only ^99! 


ADB I/O lets your customers' Macs control things, it lets them fed. 

I ADB I/O lets the Mac be part of the physical world. 

P Thousands of Uses 

Science, Multimedia, Children's Museums, Home Automation, 
Theatre Stages, Industrial Testing, Medical Research, Bonsai 
Watering, Robotics, Weather Stations—anything that can 
[ye. dectronically measured or controlled can use the ADB I/O. 

No Serial Ports Occupied 

ADB I/O uses the Apple Desktop Bus to communicate inputs and 
oulpuls lo and from your Macintosh. (Maximum polling frequency 
is 90 11/.) No cxlcrnal power supply is needed. 

Eight I/O Channels Provided 

Four relays for output. Four channels for Digital In, 

Digital Out or 8-bit Analog In. 

Extensive Software Support 

With ADB I/O and nearly any environment* 
it is easy to build customized 
applications for your control and 
data acquisition needs. 

For more info, visit us at 
www.bzzzzzz.com. 
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SiteManager 


Finally! - Site Management for BBEdit 


For more information • For a comprehensive product overview and descriptions/ 
examples of how our customers are increasing their web productivity, visit our 
web site at www.digitalcomet.com or email us at info@digitalcomet.com 


SiteManager gives you complete site management capabilities, 
without leaving BBEdit. Manage site-wide changes, a consistent 
library of page templates, cgi extensions and more — all with a 
drag and drop interface. 

Free download and $10 off at 
www.dlgitalcomet.com/mactech/ 
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QD3D since its original release (and will no doubt come some 
day). But the reality is, it may be a while before you’ll see 
convincing smoke or fog effects in QuickDraw 3D (unless you 
write your own custom rendering plug-ins). 


suitable data strucaires with which to maintain spatial data) can 
be challenging, to say the least. You not only need the flexibility 
to handle arbitrarily complex shapes, but you need to be able to 
make changes to those shapes on the tty and associate a variety 
of important attributes (like color, transparency, specularity, etc.) 
with various portions of various objects. Traditionally, 3D graphics 
programmers have come at the “geometiy representation” 
problem either by encoding shapes implicitly (using pure 
mathematics), or by representing shapes explicitly, via large grids 
or meshes. (Tlie 2D analog to this situation is vector versus bitmap 
graphics.) The advantages of the pure-math approach include 
efficient use of RAM and resolution independence. The chief 
disadvantage of this approach is lack of flexibility: It’s often just 
not practical to try to represent complex shapes in tenns of, say, 
NURB patches. (NURB stands for non-uniforrn rational B-spline, 
and a patch is a surface based on cui*ves. For an explanation of 
these concepts, see any good graphics text.) 

A somewhat more flexible alternative to implicit modelling is 
explicit ret)revSentaLion of geometry tlirough vertex arrays. This 
time-lionored approach has the advantage of letting the 
programmer model shapes of arbitrary complexity, to any desired 
degree of accuracy (RAM permitting). The downside of the brute- 
force “big mesh” method should be obvious: For all but the most 
trivial objects and scenes, we’re talking about huge amounts of 
array indirection, array reallocation, and array storage. Even if RAM 
is no problem, managing all that array data can be a nightmare. 

Most programmers would agree that the only reasonable way 
to approach this kind of data-manipulation nightmare is to impose 
an object paradigm on it, so that data is hidden when necessary, 
visible when necessary, and the division of responsibilities between 
and among objects can be known in advance and enforced. This is 
the approach taken by QuiclcDraw 3D. 


The QD3D Way 

Bear in mind as we forge ahead that there are several aspects 
to the 3D programming problem, each one vitally important: 

• Geometry creation: I low to create, represent, modify, and 
manipulate 3D geometries. (This also has a non-trivial 
human interface aspect: How best to enable the computer 
user to accomplish the geometry creation task — still pretty 
much an open question.) 

• Geometry presenlalion (scene arrangement, lighting, and 
rendering). If you can’t present your 3D data in 2D form, your 
efforts, in all likelihood, have been for naught. 

• Geometiy transportation (i.e., reading and writing 3D data to 
various {physical and virtual media for purposes of storage 
and interchange). 

QuickDraw 3D offers interesting solutions in all three areas. 
We’ll get to the presentation and transportation issues some 
other lime, but right now let’s lake a look at the geometry- 
creation problem. 

The digital representation of 3D geometries (that is, finding 
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Figure 1. QuickDraw 3D has a well defined object hierarchy. 

QD3D is an ohjecl-hased system, in that just about 
eveiything is an object with a position in a well-defined hierarchy 
(see Figure 1). Don’t be put off by this if you’re not an object- 
oriented programmer. To use QuickDraw 3D, you don’t have to 
know a bit of C++, because the API is entirely implemented in 
procedural C. (A Pascal interface is also available; check Apple’s 
web site.) What’s important here is that by encapsulating 
geometric data and methods in objects, Apple has succeeded in 
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hiding a lot of the ugly details of geometry manipulation (and 
storage) from the programmer, while enforcing uniform 
behavior, yet allowing access, when necessary, to objects’ 
internals. And the good news is, you can use implicit or explicit 
geometries, or both. Qr)3r) accommodates conics, quadrics, 
quartics, and NURB patches, as well as a rich set of polyhedral- 
mesh tools — the best of both worlds. 

Nomenciatijre 

Of course, an object-oriented system the size of QuickDraw 
3D could easily become overwhelming if classes, methods, and 
constants were not organized according to an intuitive and 
consistent naming .scheme. This is one area where QD3D really 
shines. For example, function names always begin with ‘Q3’ and 
take the form ClassName_Method Thus, Q3Triangle_GetData() is 
a function defined in the Tnangle class that fetches a triangle’s 
data. Likewise, the function Q30bject_Dispose() is defined in the 
Object class and disposes of any object passed as an argument. 
Note that since Object is the system’s root class, 
Q30bject ^DisposeO can actually operate on any kind of object, 
including Triangles, which (like other geometric objects) are at 
the bouom of the QD3D class hierarchy. 

Classes and class data structures follow a similar self- 
documenting nomenclature. All class names (and related data 
structures) begin with TQ3’, so that, for example, lights are 
TQ3LightObjects, shaders are TQ3Shader0bjects, etc. 

Constants begin with ‘kQ3’ and take the form 
CategoryTypeOption, as in kQ3GeometryTypeBox or 
kQ3TransformTypeRotate. 

The bottom line is that just by reading the variable and 
function names, you can usually figure out what something does 
in QD3D — a good model for all of us to follow. 

Object Sharing and Dereferencing 

One of the strong points of QD3D is the way it promotes 
object sharing, which results in efficient storage and low 
computational overhead for many types of 3D operations. The 
vast majority of objects you’ll work with in QD3D will inherit 
from the Shared class. Tliere can be multiple references to shared 
objects (hence the name), but this gives rise to a serious 
programming concern in that someone, somewhere, has to keep 
track of all the references to all the ol)jects so that objects that 
are no longer needed don’t persist and cause memory leaks. 
QuickDraw 3D keeps track of shared objects by means of a 
reference count, initially set to 1 the first time an object comes 
into existence. For example: 

myNewPoInt “ Q3Pojnt_New( &point.Data ): 

// myNewPoint now has a reference count of 1 
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Once you’ve created an object, you may want to add it to a 
group, like this: 

Q3Croup_Add0bjGct( myCroup, myNewPoint ); 

// myNewPoini’s reference count is incremented 

Note that after the foregoing two calls are made, 
myNewPoint has a reference count of 2. But once you’ve added 
the point to the group, there is no need to keep the second copy 
around. So it’s important to decrement the reference count by 
means of a dispose call: 

Q30bject_Dispose( myNewPoint ); 

// the reference count for myNewPoint is decremented 

What confuses a lot of newcomers is that the call to 
Q30bject_Dispose doesn’t necessarily eradicate the object or its 
data from memory; there will always be a copy of the object in 
memory as long as the reference count is greater than zero. To 
delete an ohjecl from memory completely, you must call 
Q30bject_Dispose enough times to decrement the object’s 
reference count to zero. 

It’s important to make dispose calls when copies of objects 
are no longer needed, because failure to do so will cause serious 
memory leaks as your program’s heap fills up with unused 
objects. But by the same token, you don’t want to dereference an 
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object too many times, or the reference count might go to zero 
when there are still routines counting on the object being there. 
(This is a good way to crash.) The rule is, you should dispose of 
an object before the scope of the variable expires. Example: 

( // Beginning of block; variables come into scope. 

TQ3Georaetry0bject myObject = Q3Mesh_New(); 

// Do something with myObject. 

//The scope of myObject will end at the next 
// closing brace, so be sure to dispose of it 
// before we go out of scope: 

Q30bject_Dispof5e( myObject ); 

) // End of blcK'k. 

That’s ail there is to it. Disposing of objects as soon as 
they’re not needed quickly becomes second nature, with a little 
practice. Follow this rule and you’ll never get in trouble with 
memory leaks in QD3D. (Well, maybe not never, but you get the 
idea. Failing to dereference objects properly is the No. 1 most 
popular way to generate memoiy leaks in QD3D.) 

What about Group objects? 'the good news here is that 
when you dispose of a group with Q30bject_Dispose(), 
QuickDraw 3D takes care of disposing of the individual 
constituents for you. In other words, if you have a Group that 
contains three 'I'ransform objects, four AttributeSet objects, and 
two dozen Geometiy objects, you don'tn^(ic\ to loop over all the 
members of the grou[) and dispose of them one by one. QD3D 
does this automatically when you tell it to dispose of the group. 

Staying out of Trouble 

Before we move on to some actual code, let’s spend a minute 
talking about whal il lakes to produce bug-free, leak-free code in 
a QD3D app. (It’s possible. Don’t believe the rumors.) We’ve 
already mentioned the object-dereferencing gotcha. 'Ihe next most 
important caveat involves uninitialized variables: in paiticular, 
unassigned attributes. Many of the data structures that QuickDraw 
3D uses to create objects (inc'liiding almost all of the geometric 
objects, from points on up) include a TQ3AttributeSet field. 'This is 
so you can apply colors, transparency, etc. to geometiy 
comf)onents in a selective fashion. It does not mean you can ignore 
the TQ3AttributeSet field in tho.se ca.ses where you don’t want to 
apply colors or other effects. Ihe rule is: Whenever a cktta structure 
contains an attribute field, you should always set that field either to 
a valid AttributeSet object, created with Q3AttributeSet_New(), or set 
it to NIL. If you don ’t intend to assign an attiibute, set the J'ield to 
NIL Failure to do so niay cause your application to crash. (It’s kind 
of like some of the low-level File Manager calls that expect storage 
to be set for the ioName field of a parameter block, even if you 
don’t supply an acuial name.) Leaving a garbage value in the 
attribute field of a data stmeture is an invitation to disaster. 

You can get a variety of strange bugs in your QD3D app if 
you aren’t aware of certain compiler issues. First, l)e sure all 
enumerated constants are of the four-byte int variety. Tf you let 


shorts or longs be used in enums, it’s likely QuickDraw 3D will 
interpret your constants incorrectly, which could be disastrous 
given the huge number of enumerated constants in QD3D. In 
CodeWarrior, go into Project Settings and set the 4-bytc enum 
option. In other development environments you may need to 
issue the appropriate #pragma directive. 

QD3D also expects pointers or data of type long, float, or 
double to be aligned on longword boundaries. The QD3D.h 
interface file (included in the SDK) contains appropriate #pragma 
directives for several popular C compilers. Check to be sure 
yours is included. 

QuickDraw 3D defines several levels of abnormal conditions 
that are flaggable. An error is a generally nonrccoverable 
condition that causes the currently executing QD3D routine to 
fail, perhaps fatally. A ivarning is an unexpected condition that 
could lead to an error if your application continues execution 
without handling the warning. A notice is an unexpected 
condition that, because it is le.ss adverse than either an eiTor or 
a warning, probably will not cause immediate problems, but is 
sufficiently abnormal to warrant flagging. QuickDraw 3D notifies 
your application of errors, warnings, and notices by executing 
application-defined callback routines that you have previously 
registered with the QD3D Error Manager. Implementation details 
are described fully in the Addison-Wesley book 3D Graphics 
Programming with QuickDraw 3D (available online; see end of 
article) and Apple’s SDK contains sample code and iieadcrs for 
ready-to-use error handlers. Once a handler has been defined 
and declared, installing it takes just one line of code: 

Q3Error Regi.‘3tGr( MyErrorHandler, OL ); 

The result is that when QD3D encounters an abnormal 
condition in your program, your handler can either put up an 
approf)riate alert box or write a log file to disk (or take other 
action as you see fit). 

Apple has facilitated the bug-squashing process by including 
special “debug” versions of the various QuickDraw 3D 
extensions, and a special app called “3Dcbug,” with the 
QuickDraw 3D SDK. The debug versions of the extensions 
generate informative error mes.sages in great abundance, and the 
3Debug app lets you watch for memory leaks, making the 
development process much easier and faster. If you use these 
tools as intended, you won’t find yourself spending nearly so 
much time posting newbie que.stions to the QD3D mailing list 
along the lines of “Why does my application crash when I exit 
QuickDraw 3D?” (The answer to that one is usually: You didn’t 
manage your reference counts correctly. See above. ) 

A Quick Test 

If you’ve paid attention so far, you should have no trouble 
passing a quick cjuiz. See if you can spot the bug in the following 
line of code: 

Q3Group_AddObject(rayCroup, Q3Point_New( &inyPoiritDaLa )); 
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This nested call, which creates a new Point “in place” and 
adds it to the myGroup object, will compile, link, and run without 
errors. But it will leak memory. Why? Because the Point object 
created by Q3Point_New() has a reference count of 2 when this 
code is done executing, and there is no way to decrement the 
reference count properly. If you write it out in multiple lines of 
code, assigning the output of Q3Point_New() to a local variable, 
you’ll see the problem — and the solution. 

myPoint =Q3Point_New( &myPointData ); 

// myPoint has a reference count of 1 

Q3Group_AddObject(myGroup, myPoint); 

// myPoint has a reference count of 2 

Q30bject_Dispose( myPoint ): 

// myPoint has a reference count of 1 

Note the proper way of doing things, which is to create the 
object in a local variable, pass it as an argument, then dispose of it. 

iNITIALIZINf; ANl) ExiTINCi QD3D 

Before you use QuickDraw 3D, you should determine 
whether it is available on the host system and has been duly 
recognized by the Code Fragment Manager. First, you should 
check to see if the address of the Q3lnitialize function has been 
resolved, with a function like the following: 


Boolean MyComputerHasQD3D( void ) 

{ 

return ((Boolean) Q3Initialize != 
kUnrefSolvedSymbolAddress) ; 

] 

If Q3lnitialize has been resolved, you should now call it to 
initialize QuickDraw 3D: 

OSErr MyIniLiall2:cQD3r)( void ) 

{ 

TQ3Status myStatus; 

myStatus = Q3Initialize(); 

if ( myStatu.‘5 1= kQ3Suc.ce.‘5s ) 

DebugSLr( “\pQD3D not available!” ); 

return noErr; 

) 

MOvSt often, QD3D routines return a value of kQ3Success or 
kQ3Failure. (There are many other values, however; check out 
the header file QD3DErrors.h.) Note that kQ3Success is not the 
same as noErr. In fact, kQ3Success has a value of 1 whereas noErr 
and kQ 3 Failure have a value of zero. Don’t use your usual “noErr” 
error-checking habits with QD3D or you may am into trouble. 

When you’re done using QuickDraw 3D (i.e., at program 
termination), you should call Q3Exit() to close the eonnection: 


July 1998 • MacHTech 


3D Progkamming with QuickDraw” 3D 


25 
















myStatUf; = Q3Exit (); 

if ( myStatus != kQ3Success ) 

DebugStr( “\pQ3Exit returned failure." }; 

If your program drops into the debugger when you make 
this call, it’s probai)ly because you failed to dispose of one or 
more QD3D objects properly. Re sure to write a cleanup routine 
that disposes of any persistent objects in your app (such as View 
objects) at program termination. 

Hello World 

Creating geometric objects in QD3D is very straightforward 
— anticlimactic, even. But recall that geometry creation is only 
one aspect of 3D programming. Getting your objects to show up 
on the screen is another matter. (Providing for easy user 
interaction is yet another cylinder-of-worms.) Achieving the 
equivalent of “Hello World” in QD3D takes several hundred lines 
of setup code. Part of the reason for this is the amount of control 
QD3D gives the programmer: You have the power to set scores 
of parameters (involving lights, camera positioning, drawing 
styles, and object attributes) any way you want. Apple recognized 
that this might create confusion for non-graphics programmers 
whose only goal might be to put a 3D model on the screen for a 
short period of time. Accordingly, QD3D includes a 3D Viewer 
library that provides a high-level interface for displaying 3D 
objects quickly and easily. If you’re willing to give up a lot of the 
control you’d othei'wise have over the sc.ores of parameters that 
go into creating a scene from scratch, the 3D Viewer is something 
you should look into. (See Chapter 2 of 3D Graphics 
Programming with QuickDraw 3D or the article by Nick 
Thompson in develop No. 29.) Working with the 3D Viewer is a 
lot like working with QuickTime Movie Controllers. With just a 
few lines of code (literally!), you can get a completely functional 
user interface on the screen in no time, with minimum pain. 

Working with the 3D Viewer doesn’t really teach us much 
about QuickDraw 3D, however, any more than using Movie 
Controllers teaches you much about the QuickTime architecture. 
Hence, we’re going to skip over the 3D Viewer routines and go 
straight to hand-crafting a scene. Our first sample app, Spinning 
Thang, shows how to put a variety of objects on the screen and 
animate them. (Note that in the QD3D subculture, there are no 
things — only lhangs.) In the code for Spinning Thang. there’s 
a lot of rnore-or-less standard textbook example code for such 
routine tasks as setting up lights, cameras, and views. But there 
are a few twists, too, such as: 

• Code for making QD3D render to a limited portion (or 
“pane”) of a window. To make the pane easier to see, we also 
set the QD3D background color to grey. 

• Code for creating several different geometries, including 
some of the newer primitives that shipped with QD3D 1.5, 
such as the ellipsoid, cone, and torus. 

• Object cloning: 3D objects are drawn in qiiadmplicate, then 
rotated as a set. 


• On-the-fly scene recreation: When you choose a different 
primitive from the Geometry menu, Spinning Thang disposes 
of the old scene and recreates a new one (with the new 
geometry) from scratch, quickly and without memoiy leaks. 

• Code showing how to attach different colors to different 
portions of a geometry. 

• Algorithmic animation: Just for fun, we modify one axis of the 
rotation with a trig function. (You’d think this sort of thing 
might slow our animation down, but it doesn’t — it just 
makes it more fun to watch.) 

To keep the code as simple as possible. I’ve made 
Spinning Thang a “resource-less” app; all menus and windows 
are created programmatically, on the fly. Also, to keep the code 
readable I’ve been rather lax with error-checking. In a real 
application, you would handle error-checking much more 
rigorously. But our compiled app is less than 12K in size, 
compiles with no warnings, and doesn’t elicit any complaints 
from QD3D. (Space doesn’t permit listing all 1,000 or .so lines of 
C code here, so be sure to check this month’s CD or the 
MacTech web site for the full project.) 

Creating Geometric Objeos 

QuickDraw 3D has a rich set of built-in primitives, ranging 
from lines and triangles to cubes, ellipsoids, and tori, not to 
mention the powerful freeform polyhedral f)rimitivcs (of which 
there are currently four different types). Most of the 20 or so 
primitives are created in a similar fashion, wliich involves first 
filling out the fields of a data strucaire unique to the geometry in 
cjLiestion, then passing a pointer to that data structure to a 
“Geometry_New()” function. For example, to create a box, you 
declare a TQSBoxData data stnicture and fill in the fields as follows: 

typedef struct TQSBoxData { 

TQ3Point3D origin; 

TQ3Vector3D orientation: 

TQ3Vector3D majorAxis; 

TQ3Vector3D minoiAxis; 

TQSAttributeSet *faceAttributeSet: 

TQSAttributeSet boxAttributeSet; 

1 TQSBoxData: 

TQSBoxData myBoxData; 

Q3Point3D_Set(&myBoxData.origin, 0.0, 0.0, 0.0 ); 
Q3Vector3D_Set{fitrayBoxData.orientation, 0.0, 1.0, 0.0); 
Q3Vector3D_Set({ifinyBoxData.majorAxis. 0.0, 0.0. 1.0); 
Q3Vector3D_Set(&iiiyBoxData.minorAxis. 1.0, 0.0, 0.0); 

Note that all numeric arguments in QD3D are of type float. 
The box’s origin is set by a 3D point (three floats, giving x, y, and 
z coordinates). Don’t confuse the box’s “origin,” by tiie way, with 
the geometric center the box. The geometric center is actually at 
one of the corners, 'i'he box’s height, length, and width are given, 
respectively, by the orientation, majorAxis, and minorAxis fields of 
the TQSBoxData structure, which you’ll notice are 3D vectors. Why 
vectors? After all, shouldn’t the lengths of a box’s sides be scalar 
quantities? Actually, that would be true in the special case where 
the sides are 90® to one another. But in the interest of full 
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gcncralily, the autliors of QD3D wanted programmers to be able 
to skm) the directions of a box’s parallel sides in any manner. 
Hence, a box’s axes have direction as well as magnitude, letting 
you get the same effect as drawing a cube in a non-orthogonal 
coordinate system. (Imagine that you can, if you want, have x, y, 
and z axes that are not at right angles to one another.) It’s 
important to understand this point, because many of the other 
geometric primitives in QD3D work the same way. For example, 
a sphere, in QD3D, is actually a special case of an ellipsoid. It’s the 
special case where the orientation, majorAxis, and minorAxis of the 
ellipsoid are equal in magnitude and mutually orthogonal. 

After setting up the TQSBoxData data stmeture (including 
attributes: sec below), you create the geometry [)y calling 
Q3Box_New(): 

// create the box itself 

myBox = Q3Box_New( &myBoxData ); 


At this point, you can add the box to a group, .store it in a 
glol:)al, render it by itself, or do anything you want with it. Recall 
that adding it to a group object increments the box object’s 
reference count (as explained further above), so once you are 
done adding it to a persistent group object, you should decrement 
the box’s reference count by calling Q30bject_Dispose(). Listing 
1 shows a box-making function, MyNewBox(). 

listing 1; MyNc wB oxO_ 

MyNewBoxO 

Create and return a box objccL. 

static TQSGeometryObject MyNewBox( float wherex, 

float wherey, 
float wherez ) 

{ 

TQSGeometryObject myBox = nil; 

TQ3RoxData myBoxData; 

TQ3Scl0bjecL faces [6] ; 

short face; 

// set up attribute storage 

myBoxData.faceAttributeSet = faces; 

// we’ll color sides individually 
iiiyBoxDaLa .boxAt LributeSet = nil; 

MyColorBoxFaces( &rayBoxData ) ; 

// set up all the box into... 

Q3Point3D_Se.t{ &myBoxData.orIgin. wherex, wherey, wherez ); 
Q3Vector3D_Set (8(myBoxData.oricnLatiori, 0, 1, 0); 
Q3VecLoi3D_SeL (&inyBoxL)aLa.niajorAxis, 0, 0, 1); 

Q3Vector3D_Set(^myBoxData.minorAxis, 1, 0, 0); 

// create the box itself 

myBox = Q3Box_New{&myBoxData); 

// dispose of the attrib objects we created 
for{ face = 0: face < 6; face*H') 

{ 

if( myBoxData.faceAttributeSet[face] != nil ) 

Q30bject_Dispose(myBoxData.faceAttributeSet[face]); 

} 

return myBox; // return the object; if nil, caller must handle 

) 
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What happens if you later decide (after instantiating a 
geometric object) that you want to change the object’s features, 
which are accessible only via the underlying data staicture? 
QuickDraw 3D provides a rich set of daui-access calls for retrieving 
and editing object data stnictures. This means it’s possible not only 
to edit geometries (e.g., vertex coordinates) but to edit attributes 
(colors, surface normals, etc.) and — in some cases — topologies 
(the number of vertices), on tlie fly, during program operation. (If 
you’re a non-OOP programmer who balks at having to use 
accessor functions to get at geometry structures, rest assured you 
can also keep raw data structures around and render them later 
with special Submit{) calls, without ever creating an ohjecl. But the 
OOP way ha.s certain advantage.s — one being that you don’t have 
to manage tons of persistent ckita strucrtires.) 

Object Cloning 

In Spinning Thang, we store our geometries in a model, 
which is simply a Group object containing several component 
objects. Our model happens to consist of a TQ3ShaderObject (or an 
“illumination shader”), four translation transfonn objects, and four 
copies of our geometry. The transforms move the c:opies of our 
objects to various position.s in space. Wliy not just create four 
individual geometric objects, each one positioned in the “right 
place” at birth? Tliat would certainly be the right tiling to do if you 
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wanted to animate the objects individually or let the user edit or 
manipulate them individually at Rintime. But in iD work, it often 
happens that you want to create groups of objects that “fly in 
foriruition,’' or move as a group. Maylx? you want to create a 
meteor held containing 100 (or 1,000) like-sized n)cks, or a giant 
wave of 8th Air Force lx)ml:)ers on a raid over Berlin. If each 
individual meteor (or lx)mlx?r) consists of a 10,000-polygon mesh, 
it would be extremely wasteful of RAM to have to store each object 
individually, and it would require lots of CPU cycles to aj:)ply 
rotations, translations, etc. individually to each object. The smart 
way to do this is to clone one meteor (or bomber) multiple rimes, 
curling storage and com|:)utational requirements drastically, 'fhe 
code in MyNewModel(), Listing 2, illustrates how to do this. 


Listing 2: MyNewModelO 

MyNt*wlV1(Kk*l() 

Create and return a group object containing an illumination shader 
and our cloned geometr)'. Notice that once the geometric object 
is added to the group object, we dispose of its reference. 

TQ3Group0bject MyNewModeKlong geomeiry) 

I 

TQ3Group0bject myGroup = nil: 

TQ3Gpometry0bject myGeometry: 

TQ3Shader0bject myllluminationShader ; 

TQ3Veetor3D translation; 

// Create a gn)up for the complete model. 

if ((myGroup - Q3DispiayGroup_New()) != nil ) ( 


// Define a sliading type lor the group 
// and add the shader to the group 

myllluminationShader = Q3PhongIllumination_New(): 
Q3Group_Add0bject(myCroup. myllluminationShader); 
if( myllluminationShader ) 

Q30bject Dispose(myllluminationShader); 

switch (geometry) I 

case BOX : 

myGeometry ^ MyNewBox( -O.S, -O.b. 0.!) ); 

break; 

case CYLINDER : 

myGeometry = MyNewCylinder( -0.5, -0.5, -0.5 ); 
break; 

case ELLIPSOID : 

myGeometry = MyNewEllipsoid( 0.5, 0.5, -0.5 ); 

break; 

case TORUS : 

myGeometry “ MyNewTorus( 0.5, -0.5. 0,5 ): 

break; 
case CONE : 

luyGeomelry = MyNcwCone( -0.5, -0.5, -0.5 ); 
break; 
default: 

DebugStr (‘‘\pUndefined argument to MyNewModel. *‘) ; 

) 

// pul four copies of object into the group, each one with its own translation 
translation.X = -1;translation.y ^ 0;translation.z = 1; 
MyAddTransformedObjectToGroupC myGroup. myGeometry, 

^translation ) ; 

translation.x = 2;translation.y = 0;translation.z = 0; 
MyAddTransforinedObjectToGroup( myGroup, myGeometry, 

firtran.slation ) ; 

translation.X “ 0;translation.y = 0:translation.z - 2; 

MyAddTran.sformedObjectToGroup( myGroup, myGeometry. 

Stranslation ) ; 

translation.X = 2;translation.y = 0;translation.z = 0; 

MyAddTransforraedObjectToGroup( myGroup, myGeometry, 


1 f ( myGeomet ry ) // once it’s part of gniup. dump the reference to it 

Q30bjGCt_Dlspose( myGeometry ); 

return ( myGroup ): 

1 

Notice how each translation transform “picks up” from 
where llie previous one left off, kind of like how ordinary 
QuickDraw starts drawing wherever the pen location was left at 
the end of the previous operation. Each lime the model gets 
rendered, QD3D executes the transforms sequentially, in macro¬ 
like fashion, cloning our geometry. (This means, of course, that 
you can’i color individual items in the group differently; the 
objects, after all, are clones of a single object.) 

ATTRffiUTE Objects 

An important design principle of QuickDmw 3D is that 
attributes (which, broadly speaking, means surface-related 
properties, like color and specularity) occur in AttributeSet 
objects, which are associated with geometries by means of their 
underlying data structures. Every kind of geometric object, from 
points and lines up to the meshes, has at least one 
TQSAttributeSet data field in its data siniclurc. This means that not 
only the base object but its constituent components (vertices, 
laces, etc.) have their own attribute sets, which apply in a natural 
hierarchical fashion .so ihal ihc allriliule set with the lowest-level 
association has precedence. For example, you can apply a solid 
color to a mesh object; but you could also apply colors to 
individual faces or veitices. Vertex colors, when present, “win 
out” over face colors, and face colors win out over whole-object 
colors, just as you’d expect. 

The use of attributes in this hierarchical fashion achieves a 
couple of goals. First, it gives the programmer great flexibility, 
obviously. Secondly, it kccfxs storage requirements to the 
ab.solute minimum. If you want just one fac:c of a multi-face 
object to Idc orange, and the rest of the object to be green, you 
can give the orange face one attribute .set and the object itself 
another attribute .set — there’s no need to apply unique attribute 
.sets to each and every fac'e or verrtex. Not only does this reduce 
the amount of coding for the programmer, but it greatly cases tlic 
storage and computational overhead for QD3D. 

There arc presently eleven j^redefined attribute types in 
QD3DSet.h (and you can extend these with your own custom- 
defined attributes), 'fhey include diffu,se color, specular color, 
transparency color, surface UV (parameterization), surface 
normal, and surface tangent, among others. Various object 
clas.ses (View, Group, Geometric, Face, Vertex) have their own 
natural attribute types that can Ix^ applied to them; surface 
normals, for example, make sense for a polyhedral mesh but not 
for a View object. The relationships between classes and 
attributes are spelled out in detail in Chapter 5 of 3D Graphics 
Programming with QuickDraw 3D (the official documentation 
for QD3D). For now, it’s important merely that you know: 
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1. AttributeSets are objects that have to be created and disposed 
of like any other object. 

2. An Attril^uteSet object can contain many different kinds of 
attributes, or none. (The attributes themselves are generally 
not objects: They’re things like colors and vectors.) 

3. Every geometric primitive at the level of Point or above has 
at least one AttributevSet field in its underlying data structure. 

4. The AttribuleSel field must be set to nil if it is not used. You 
don’t have to wse every AttributeSet field, but you can’t leave 
a garbage value in an unused AttributeSet field! 

Let’s go back and look at the box again. The TQ3BoxData 
data structure has two AttributeSet fields: one for faces and one 
for the entire box. You can use one or the other, or both, or 
neither. In Spinning Thang, we apply different colors to the 
individual lx)x faces. But suppose we simply want to color the 
entire box red. Here’s how: 

TQ3ColorRGR color; 

myBoxDala.faceAttributeSet = nil; 

myBoxData.boxAttributeSet ^ QSAttributeSet Ngw(); 

color, r = 1.0; //l(K)%red 

color.g = color.b = 0.0; 

Q3AlL ribuieSet_Add( myBoxData.boxAttributeSet, 
kQlAttributeTypeDiffuseColor, 

&color): 

// be sure all the other data fields are filled out 


// then crcate the l)ox... 

myBox = Q3Box_New( &inyBoxData ) ; 

// dispose of no-longer*needed Atiribuie.Set object... 
if( myBoxData.boxAiiribuLoScL != nil ) 

Q30bjor.t_Di spose(myBoxData. boxAttributeSet) ; 


Tlie lx)x will now lx* solid red. Note that we have to follow 
a definite sequence: create the AttributeSet, then add our diffuse- 
color to it, then create the box using our data simcture, then 
dispose of the AttributcSel object. (Once the box is created, it has 
its own copy of the attributes.) It wouldn’t make sense to dispose 
of our attributes before creating the box. Nor do we let the unused 
AttributeSet object persist after myBoxData goes out of scope. 

Notice, incidentally, tliat QD3D uses an RGB color model, but 
a TQSColorRGB is not the same as a Color QuickDraw RGBColor. The 
latter uses three unsigned shorts. (If you want to convert between the 
two types, you’ll have to write your own utility routine.) 

By now, you’re either totally confu.sed, or .some of this is 
actually starling to make .sen.se — in which case you just might 
be getting h(X)ked. (Watch out.) 
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Drawing 

Once you liave a geometry, actually disl)laying it rec|uires that 
you create a View object, which is a coUeaion of objects needed to 
render a serene, namely: c'amera, lights, draw context, and tenderer. 
If you understand how geometric objects are created, tlie creation 
of cameras, lights, etc. will seem nauiral to you lx^cau.se die same 
overall methodology applies. Only the underlying data structures 
will Ik* unfamiliar (aldiough if youVe spent any time using 
commercial 30 packages, many of die concepts should ring a tell). 

One object that may be rather unfamiliar-sounding at first is 
the DrawContext. I’his is simply QD3D's analog of the Grafl^irl 
(a place to draw), except that it is designed to be much more 
general. QuickDraw 3D is a cross-platform libraiy, which means 
(for example) that it needs to be able to draw into more than one 
kind of windowing system. The rest of the API needs to be 
insulated from the machine-specific implementation details of 
drawing into various kinds of windows. The DrawContext object 
layer achieves that. 

When QD3D is ainning under the MacOS, it can use two 
specific kinds of draw contexts: a so-called Macintosh draw 
context, or a pixmap (or offscreen) draw context. The former lets 
QD3D draw into CGrafPorts while the latter lets QD3D draw into 
GWorlds or memory. (You don’t huDe to use pixmaps associated 
with GWorlds, incidentally: You can force QD3D to draw straight 
into any arbitrary address in memoiy, if you want.) Why would 
you want to draw into memory yourself, when QD3D already 
handles double-buffering for you? Well, for one thing, you might 
want to be able to output your renderings as PICI’ files. You 
might want to put PICTs on the scrap, or insert them directly into 
a QuickTime movie. You might want to apply 2D convolutions 
or filters to your renderings. Or you might want to combine 
images offscreen to achieve special compositing effects, such as 
underlays or overlays. There are lots of possibilities. (Maybe we’ll 
explore some of them in future articles.) 

When drawing into a CGrafPort, it’s not necessary to give 
QD3D control over the entire window. In Spinning Thang, we 
show how to make drawing occur in a specified portion of a 
window (a “pane”) — a technique that comes in handy when you 
need to draw inside dialogs or alerts, for example. (We also show 
how to set the “clear color” — or background color — to whatever 
color you want it to be.) The source code is pretty self-explanaioiy, 
excef)t maylx? for one thing: When drawing to a restricted portion 
(or pane) inside a window, you want to lx* doubly sure to alert 
QD3D to the height/width ratio of the pane; otherwise your objects 
could look stretched or squashed. The solution is simple: When 
.setting uf) your camera data, set the aspectRatioXToY field of the 
TQSViewAngleAspectCameraData .struaure to reflect the aspect ratio 
of the pane, not the ooerall mndou). 

Space doesn’t permit an exhaustive discussion here of the 
details of setting up camera and light objects. For an excellent 
discussion of the basic techniques, see Brian Greenstone’s 
introduction to QD3D in Chapter 9 of Tricks of the Mac Game 
Programming Gurus (Hayden Books). 


Rendering 

So, how do you draw something in QD3D? llie answer is, 
you set up a rendering l(K)p. This is anotlier example of an area 
where the QD3D way of doing things often catches Ixginners 
off-guard, so let’s spend a moment talking about it. 

In QD3D, each element of a scene must be “submitted” to the 
renderer, in a particular order. Style and shader objeas have to be 
submitted before geometries, for example, Ixcause QD3D needs to 
know how to properly represent visible objects tefore they can be 
drawn. Rendering is done in a do-while loop, to allow for the 
possibility that rendering might have to be done in passes, (lliis 
really isn’t a concern when using Apple’s renderer, wliich finishes 
in one pass, but a raytracing or radiosity renderer could, in tlieory, 
require multiple passes.) 'I’he screen-drawing hmetion from 
Spinning Tliang is shown in its entirety in Listing 3- 

Listin g 3: Docume ntPrawO _ 

D(x:umentDniwO 

lliis is Uie main drawing routine in our sample app. 

TQ3Status DocumentDraw( DocumentPtr theDocument ) 

( 

TQ3Status statu.s; 

status = Q3ViGw_StariRendering(thcDocument->fView ); 
if (status != kQ3Success) 

DebugStr(“\pTrouble with StartRenderingO.; 

do ( 

Q3SLylG_Subinit( theDocument->fInterpolation, 
theDocument >fView ); 

Q3Style_Subinit ( theDocument - >fBackfacing, 
theDocument->fView ); 

Q3Style_Subinit ( theDocument->fFillStyie, 
theDocument->fView ): 

Q3MatrixTransform_Subrait( ^theDocument*>fRotation, 
iheDocument->fView ); 

Q3DisplayGroup_Submit( theDocument->fModel, 
theDocument->fView ); 

1 while (Q3View_EndRendering(theDocument->fView) = 
kQ3ViewStatusRetraverse ); 
return kQ3Success ; 

I 

Rendering Ixgins wiili a call lo Q3View_StartRendering(), which 
tells QD3D to prepare for drawing using our View object. (Note that 
in Spinning Thang, all of our persistent sc:ene objects are 
conveniently stored in a single application-defined data stmcuire, the 
DocumentRec; see below.) One by one, we submit our Style objects 
(the exact order of these isn’t important); then a transfonn matrix to 
pertbrm our (global) rotations; and finally our geometry. As we make 
these “submit” calls, QD3D constaicts the scene offscreen (assuming 
double-buffering is enabled in our Drawliontext); then when 
Q3View_EndRendering() is called, the image, if it’s ready, Ls blitted to 
tlie .screen. If it’s not ready, the kxip cycles. 

struct _documentRecord I 

TQ3ViewOb j ect fView ; // the view for the scene 

TQ3GroupObject fModel ; //objeci in ihe scene being modelled 

TQ3Styl eObject fInterpolation : // inlerpolalion slyle used wlien rendering 
TQ3Styl eObject fBackFacing : //backface removal 

TQ3S tyleOb jec L fFi 11 Styl e : // draw as .solid filled object? 

TQ3Matrix4x4 fRotation; // the rotate tran.sform for the model 

): 

typedef struct _documentRecord DocumentRec. ‘DocumentPtr, 
**DocumentHdl ; 
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FTP Parameters 


W Description 


FTP Host 


Directory 


leoord 


User ID 


Type of file tr^ 

G MacBinary File 


Set these parairi 
(sending) files i| 


TCP/IP Scripting Addition The Internet Scripting Solution 


The TCP/IP Scripting Addition allows you to quickly 
develop Internet client/server applications using 
AppleScript®. If you want to script with MacTCP"'^' and 
Open Transport^*^, here's your solution! 

♦ Supports WebSTAR"'^, FaceSpan"'", and HyperCard 

♦ The industry standard product for scripting 
Internet applications since 1993 

♦ Sample scripts include FTP, HTTP, 

Telnet, Post Office, E-Mail and more 

♦ Featured on the Apple® Internet Server 

Order now through Developer Depot at 
800-MACDEV-1 or other mail order stores 


Mango Tree Software, Inc. 

Box 10S7 • Brookline, Massachusetts USA 02146 
Fax / Voice 617-522-2480 
saics@man>>olrce.com • www.man^^olrcc.com 


All Irademarks are properties of their respective holders. 

Contact Mango Tree Software for site licensing and redistribution information. 
Copyright €) 1993-8 Mango Tree Software, Inc. 


Telnet Librt 


Telnet Library v1.0 

Copyright © 1995 Mango Tree 
All Rights Reserved 


set myJelnet^stream to telne 
tell my_telnet-.^tream 

try 

connect(your_ho3t) 
r ead u nti 1 text ("1 oc 


Note dial somewficrc in all this, diere needs lo loe an 
Tllumination Shader object, to .set the Tenderer’s illumination model 
to Lambert, Phong, or Null. (Consult a graphics text for 
mathematical details of these metliods. Phong is essentially Ltmbert 
shading with specular highlights added. Null is an option dial lets 
you shade objec:Ls uniformly, without respect to light direction.) In 
Spinning Thang, the illumination shader is attached to the model 
(the group object that contains our geometry). But it doesn’t have to 
be. It could be submitted individually in die rendering loop. 

Any number of additional objects (geometries, transforms, 
group objects containing combinations of other objects, etc.) 
can be submitted in the rendering loop. It all depends on what 
you need to draw. 

Looking to the Future 

We’ve covered a lot of ground in just a few pages, but 
even so, we’ve really only begun to scratch the surface of 
QD3D. Thoroughly exploring QuickDraw 3D would require 
volumes. We haven’t even touched on such important topics 
as texture mapping, freeform mesh geometries, file objects, or 
the 3D Metafile Format, let alone user-interface issues. But by 
now, you should have some appreciation for the power and 
scope of QuickDraw 3D. With a little imagination, QD3D can 
take you to some pretty interesting places. Imagine putting 
custom 3D controls in your dialog boxes; doing 3D camera 
fly-throughs of 3D-plotted data; connecting QD3D’s Pointing 


Device Manager to a MIDI controller and using QuickTime’s 
MIDI-track facilities to create, edit, record, and play back 
intricate, gestural animations; modelling a new gadget in 
QD3D and outputting it in QuickTimeVR formal for others to 
play with; or showing a QuickTime movie on the surfaces of 
a spinning cube. (Code for the last two tasks can be found 
on Apple’s web site.) The mixing of QuickTime and QD3D 
capabilities is an especially exciting prospect for animators. 
And to think, you can harne.ss all of this magic and still 
produce cross-platform code. 

No matter what aspect of the 3D graphics programming 
challenge you want to tackle, QuickDraw 3D has a variety of 
tools that can help you realize your dream. How far you take 
it is up to you. 


Want to share a URL with 
the community? 
Send it in to 

<mailto:urls@niactech.com> 
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Desktop VR using QuickDraw 3D, Part I 


Using the View Plane Camera 
for Implementation of a Head- 
Tracked Display 


Summary 

Woulcln’i ii Ik? ax>l to \yc able to look 
around tliree dimensional objects displayed 
on your monitor by moving your head, just 
as if' the objects were standing there? Kind 
of like a hologram, but with the flexibility 
of 31) computer graphics. Futuristic and 
expensive? It could be easier and cheaper 
than you think. In a two part article we 
explain how to implement such a system, 
also known as a head tracked display, on a 
PowerMacintosh. Head-tracked pei'spective 
provides the user witli a sense of depth 
without die use of stereoscopy. 'lb facilitate 
implementation we use QuickDraw 3D, 
Apple's 3D graphics library. In temis of 
hardware all you need is a PowerMac with 
QuickDraw 3D, an absolute position¬ 
measuring device with three degrees of 
freedom and, preferably, a QuickDraw 3D 
accelerator board. 'Phis month we discuss 
the graphics-related aspects of a head- 
tracked display. Next month, we will 
discuvss the hardware-related aspects. 


iNTRODUCnON 

When we move about in everyday life we see objects in our 
environment from different perspectives. As we do this it appears 
that objects at different relative depths shift with respect to each 
other. This phenomenon, called movement parallax, is a very 
strong depth cue. It is possible to mimic movement parallax in 
virtual reality systems. In immersive Virtual Reality (VR) (where 
the user wears a helmet) movement parallax is combined with 
stereoscopy. Apart from immersive systems there is also another 
category of VR systems called Desktop VR which uses a 
conventional monitor. Desktop VR is a rather broad term which 
can mean anything from a simple system showing a perspective 
“walk-through” with mouse interactivity, to a complex system 
using both stereoscopy and movement parallax. With immersive 
VR the user’s real environment is completely replaced by a virtual 
one, while with desktop VR a virtual scene is emtedded within 
the user’s real environment. One of the good things about a 
desktop VR system which uses movement parallax only is tliat the 
user’s 3D impression is considerably improved without the need 
for some kind of 3D glasses and stereo rendering. For movement 
parallax, all that is needed is a way of determining the user’s head 
pcksition. As a re.sult only a minimum of headwc^ar is required. 

When the user lcx)ks around a virtual scene displayed on a 
monitor, his head position changes, which can be detected by 
means of a position sensor attached to his head. In response the 
computer can update the perspective of the scene shown on the 
monitor in accordance with his new head position. The result is 
that the user can look around the objects in the virtual scene as 
if they were standing in front of him (Figure 1). 


Tom Djajadiningrat (J.P.Djajadiningnil@i().TUnelft.nl) is an industrial designer interested in products and computers which are 
intuitive in use. When not trying to convince others that he will now finish his PhD thesis on interfaces using head-tracked 
displays Yeally .soon’, or ha.ssling Maarten and the QuickDraw 3D mailing list willi silly programming que.stions, he dreams of 
designing the 25th anniversary Macintosh. 

Maarten Gribnau (M.W.Grihnau@io.TlJDelft.nl) is an electrical engineer interested in Computer Graphics and Interaction 
Design. He has successfully delayed Tom’s re.search project so they can now both convince others that they will complete their 
PhD theses ‘really soon’. Apart from his research on two-handed interfaces for 3D modeling applications, he occasionally drinks 
a strong cup of Java when he is trying to program the ultimate internet golf game. 
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Figure /. An observer looking at a mrtiial house displayed on a 
head-tracked display. By moinng his head to the right, he ineivs 
the house from the right. By moving his head to the left, he mews 
the house from the left. 

l^Tccplion psychology uses the term movement parallax to 
describe a particular depth cue. In the human-interfacing 
community many terms are used to devSeribe desktt)p VR sysieriLS 
which make use of the movement parallax depth cue. These 
terms include head-tracked display, head-slaved viitual camera, 
animated perspective and virtual window system. In this article 
we will use the term head-tracked display. 

A Head-Tracked Display on the Mac 

Required and recommended software and hardware 

What you need is a PowerMacintosh, QuickDraw 3D 1.5.3, 
a position sensor with three degrees of freedom, and preferably 
a QitickDraw 3D accelerator card. We u.se QuickDraw 3D 
because it facilitates communication with input devices, and 
implementation of the correct coupling between head position 
and camera movement. 

The position sensor needs to detec:t position with three 
degrees of freedom and needs to l)e suitable for attaching to the 
head. A low cost option is to use a FreeD (formerly known as 
the “Owl”) ultrasonic tracker by Pegasus Technologies. Other, 
more accurate, but also more expensive options are, for 
example, a Dynasight infra-red tracker by Origin instruments or 
a Flock of Birds electro-magnetic tracker by Ascension 
Technologies. Please note that we supply basic driver 
applications and source code for the FreeD, the Dynasight and 
the Flock of Birds. We also provide information on how to 
connec.t these devices to a Macintosh computer. 

A QuickDraw 3D accelerator board is recommended 
because, with movement parallax, frame rate is quite important. 
The lower the frame rate, the longer the delay between 
establishing the sensor position and the corresponding 
perspective being displayed on the monitor. In the meantime the 
user may have moved to a different location. As a result of this 
lag, the perspective which is displayed does not match the user’s 
viewing position, lb the ti.ser this mismatch exprCvSses itself as 
distortion and instability of the virtual scene. 

What you should know 

We assume that you are familiar witli the basics of 
QuickDraw 3D programming. If you have not dealt witli 
Quic:kDraw 3D tefore we suggest that you have a look at the 


introduction to QuickDraw 3D in Develop 22 (Thomp.son and 
Fernicola, 1995) or at chapter nine “QuickDraw 3D” of “Tricks of 
the Mac Game Programming Gurus” (Greenstone, 1995). 

Overview Of The Two-Part Article 
There are two software components which together form 
our head-tracked display: a viewer application, called 
Mat'VRoom, and a driver. As mentioned previously, the 
implementation of the head-tracked dis|)lay is described in two 
parts. In this month’s graphics issue we give an explanation of 
how to control the camera by the user’s head position to show 
the c:orresponding perspective on the monitor. We also show you 
how to actually get the head-tracked display up and running. 
This section tells you how to use MaeVRoom, how to attach the 
sen.sor to your head, and how to troublesh(X)t. 

Next month, we will explain how to write tlie driver and how 
to use the Pointing Device Manager to handle the communication 
between the driver and MacWoom. We will also discuss a number 
of calibration methods to get the best possible results. 

Depending on your needs, you may wish to read parts of, 
or all of this and next month’s article. See whether you fit into 
one of the following categories and have a look at the oveiview 
(Figure 2). Note that for some of the information you will have 
to wait untill next month. 
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1. I would like to see what this head-coupled [KTspective is 
alx)Ut. I don’t have a three DOF tracker though. 

Read the section "Using your head-trucked display” to get an 
idea of what a head-tracked display involves. Play about 
with MacVRoom, it switches to mouse control in absence of 
a three DOF tracker. 

2. 1 have one of the tracking devices mentioned and would like 
to try out the head-coupled perspective. 

Read the sections "Using your head-tracked display” and 
"Calibration”. Hook up your tracker, start up the appropriate 
driver and play about with MacVRoom. 

3. 1 have a three DOF tracker, different from the ones you 
mentioned, and I would like to try it with MacVRoom. 

Read the section "The QuickDraw 3D Pointing Device 
Manager” and build a driixrfor yK)urparticular tracker. Then 
read the sections "Using you head-tracked display” and 
"Calihratio7i ”. Hook up your tracker, start up the appropriate 
driver and play about with MacVRoom. 

4. I have an serial input device and I am interested in using it in 
conjunction with the Pointing Device Manager. 1 am not 
interested in head-tracked displays. 

Read the section "The QuickDraw 3D Pointing Device 
Manager” and build a driver for your particular input device. 

5. I have one of the tracking devices mentioned and 1 want 
to incorporate a head-tracked display into my own 
QuickDraw 3D application. 

Read the section "Head-tracked Camera Methods” and 
incoriKyrate the code into your own app. Then read the 
sections "Using your head-tracked display” and "Calibration ”. 
Hook up your tracker, start up the appropriate driver and your 
head-coupled perspective enabled app. 

6. I have a three DOF tracker but it is not one you mentioned. 

1 also want to incorporate movement parallax into my own 
QuickDraw 3D application. 

Lucky you! YoiTll have to read both parts of the article completely! 
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Driver 

The QuickDraw 3D Pointing Device Manager 
Introduction to the Pointing Device Manager 
Reading Data from Serial Input Devices 
Using the QuickDraw 3D Controller Object 



Using the QuickDraw 3D Tracker Object 


Head-tracked Camera Methods 
The DVWS and Fish Tank VR 

The QuickDraw 3D View Plane Camera 

Characteristics of the View Plane Camera 
How to control the View Plane Camera 

Calibration 

Why is calibration needed? 

Driver requirements 
Calibration method 1 
Calibration method 2 
Calibration method 3 

VRoom 


USE 


Using Your Head-tracked Display 

How to Use VRoom 
Where to Place the Sensor 
Trouble Shooting 


Figure 2. Overvieiv of the tii'o-part article. The subjects which 
are colored this month are marked with a grey block. 

Head-Tracked Camera Methods 

The Delft Virtual Window System and Fish Tank VR 

When ii come.s to implementing movement parallax wc 
could use a conventional perspective camera, position it in the 
virtual world to conespond to the u.ser’s head position, and 
orient it in such a way that it always looks at the center of the 
virtual scene (Figure 3). This is what happens when you choose 
Delft Virtual Window System (DVWS) (Overbeeke et al., 1987; 
Srnets et al., 1987) from the projection menu. Such a projection 
method is also known as “on-axis” projection, because the center 
of the image coincides with the camera’s viewing axis. 
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Figure 3- Three different obserDerpositions (top row), the 
corresponding camera positions for the DVWS projection 
method (middle row), and the corresponding camera posiliom 
for the Fish Tank VR projection jnethod (bottom row). 


'l*he top row shows three different positions of an observer 
in front of a monitor. The middle row sliows the virtual camera 
which alw'ays is pointed at the fixation point F. 'I’he main 
advantage of this projection method is that it is perceptually 
robust as the virtual scene is always displayed in central 
perspective. Even if the system is not properly calibrated the 
resulting image does not appear distorted. As Figure 4 shows, 
the perspective is that of a regular photograph. This means that 
camera movement can also be scaled c()mi:)ared to observer 
movement. So the observer can look around the virtual scene 
completely and even view it from the back with relatively small 
head movements, though the scene does not appear to be 
stationary. Also, observers who are not wearing the tracker and 
who therefore do not control the perspective, still gel an 
undistorted view on a rotating scene. 

Implementation of the DVWS requires only placement 
and zooming of an ordinary QuickDraw 3D aspect ratio 
camera. We assume you are familiar with this type of camera 
and therefore do not explain it any further in this article 
Please have a look at the routines NewAspectRatioCamera (in 
ViewCreation.c) and AdjustAspectRatioCamera (in 
AspectRatioCamera.c) if you need more help. 

The disadvantage of an on-axis projection is that it is 
difficult to perfect the illusion that the virtual scene is rigidly 
connected to the physical world. When we use an on-axis 
projection with a conventional perspective camera the result is 
a perspective image of the virtual scene. However, the user 
already looks in perspective at the monitor screen which 
displays the image. The result of the compounding of 
perspectives is that lines in the virtual scene and lines in the 
real world which are meant to stay parallel do not appear to 
stay perspectively parallel when the user views the virtual scene 
from different angles. Therefore the viraial scene does not seem 
rigidly connected to the monitor. Instead it appears to rotate 
relative to the monitor. Perhaps the easiest way of thinking 
about this is as follows. Take a rectangular sheet of paper and 
tape it to your monitor so that the edges of the paper run 
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parallel to the edges of the monitor. From whatever viewpoint 
you look at the monitor and the sheet of paper, the edges of 
the monitor and the paper will always run perspectively 
parallel. In other words, they always intersect at the same 
vanishing point. If we create a virtual equivalent of the sheet of 
paper and look at it with an Aspect Ratio Camera from different 
angles, the resulting 2D image of the virtual sheet of paper will 
be perspectively distorted. Rut this is not what we want! After 
all, the physical sheet of paper never changed its shape. If we 
wish to avoid this compounding of perspectives we need to use 
a different projection method. 



Figure 4, Three perspectives according to the Delft Virtual 
Window System projection method generated by three different 
head lx)sitiorLS. From left to right: imwed from the left, from the 
middle and from the right. 
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This projection method, which is called an “off-axis” 
projection method and is often referred to as Fish Tank VR (Ware 
et al., 1993), is shown also in Figure 3. 

The lx:)ttom row shows the three virtual camera placements 
which correspond to the observer positions in the top row. Tlie 
line of sight of the virtual camera is kept perpendicular to the 
display by translating the camera without rotating it. This will 
prevent the compounding of perspective. I’he resulting images 
are shown in Figure 5. Although the pictures look distorted at 
first instance, you can find the head position from which they 
appear to look right. To find this position, use the numbers in the 
c’alibrated coordinate fields of each picture in the following 
manner. The numbers are x,y,z coordinates, multiples of the 
width of the pane with the white background. The origin of the 
coordinates is in the center of this pane. For example, to position 
your head correctly for the left picture, move your head three 
pane widths to the left, one and a half width to the top of the 
page and four widths oul of the page. 



Figure 5. Three persfxxlwes according to the Fish Tank 
/frojection method generated by three different head imitions. 
From left to right: viewed from the left, from the middle and 
from the right. 

A problem is that as the camera moves to one side, the scene 
will move off the monitor in the other direction. We need to be able 
to specify a part of the imaging plane which is oft’-axis. QuickDraw 
3D conveniently provides a View Plane camera for this purpose. 



Figure 6. The View Plane Camera. 


L isting 1 ; View Plane Ca mera data structure 

typedef struct TQSViewPlaneCameraData 
I 

TQ3CameraData cameraData; 

f loat viewPlane; // distance to view plane 

float halfWidthAtViewPlane; //dx 

float halfHeightAtViewPlane: //dy 

float CGiiterXOnViewPiane: //Cx 

float centerYOnViewPlane; //Cy 

} TQ3ViewPlaneCameraData; 


How to control the View Plane Camera 

We have chosen to use a right-handed coordinate system 
with the positive Y-axis pointing upwards and the positive Z-axis 
pointing out of the moniior. This is convenient as its orientation 
matches that of the FreeD and the Dynasight when they are put 
on top of a monitor, 'llie virtual camera always remains parallel 
to the Z-axis so that its line of sight is always perpendicular to 
the xy plane. The view plane coincides with the XY plane and 
the part of view plane which is rendered is centred around the 
world origin (Figure 7). 


The QuickDraw 3D View Piane Camera 

Characteristics of the View Plane Camera 

Figure 6 shows a View Plane Camera and Listing 1 descrilxjs 
the View Plane Camera data stiucture. Just as the lamiliar Aspect 
Ratio Camem, a View Plane Qtmera uses a struct of type 
TQ3CiimeraDaia to specify its placement, hither and yon planes, and 
view |X)rt. Tlie view plane is situated perpendicular to the c^amera 
vector at a distance spcxificxl by the view plane panimeter. the point 
where tlie chimera vector intersects the view p\imc defines the origin 
of the view plane c:(K)rdinate .system. We can S|xx:ify which part of 
the view plane we wish to render through tlie hallWicltliAtViewPlane 
(dx), lialfHeightAtViewPlane (dy), cenlerXOnViewPlane (Cx) and 
CenterYOnViewPlane (Cy) parameters. 



Figure 7. View Plane Camera looking al the display s/Kice in which 
the model a])lxiars. The line of sight of the camera always remains 
parallel to the z-axis. cl is camera location, poi is point of interest. 
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There are two pans lo controlling a View Plane Camera for 
an off-axis projection. We need some set-up code and some code 
which adjusts the camera on every nullEvent. 

The set-up code is from ViewCreation.c and is in Listing 2. 
Although the omera placement used in tills set-up function is 
adjusted immediately after start up to the tracker data, it is good 
practice to use values which ensure that the scene will be visible. 
That way if we see an image on start up wliich disappears 
immediately afterwards, we know that tlie app is rendering all right 
but that afterwards the camera placement has become garbled. 

The hither and yon planes tmneate the viewing pyramid to 
a viewing frustum. Virtual objects are clipped against this viewing 
frustum. I’o make absolutely positive that we do not get Z-buffer 
problems with acceleration cards which have only 16 bit Z- 
buffering we put the hither plane just in front of the display 
space and the yon plane jUvSt behind it. The display space is one 
QuickDraw 3D unit deep, and positioned half in front of the 
view plane and half behind it. Therefore the frontrnost point is at 
z=0.5 and backmost jxiint is at z=-0.5. On each nullEvent, we 
adjust the values of hither and yon, which are relative to the 
position of the camera, to keep the hither and yon planes at the 
same location in the world coordinate system. 

The viewport parameter lets you choose which part of the 
area you liave cut out of the view plane is mapped to the 
pane. In our case the full view port is used and is not adjusted 
on a nullEvent. 


When the camera is created the centerXOnViewPlane = 0 
and centerYOnViewPlane = 0 so that the part of the view plane 
which is rendered is centred around the world origin. The part 
of the view plane which is rendered is made one QuickDraw 3D 
unit wide, so the halfWidthAtViewPlane = 0.5. When we get to 
the section on calibration we will see why this is convenient. 'I’he 
ratio of the halfWidthAtViewPlane and halfHeightAtViewPlane 
parameters should equal that of the f)ane width and height. We 
have made it 1:V2. 1’hus the width of the display space Utkes up 
the full width of the pane, while the height of the display space 
is less than the height of the pane. This extra height is necessary 
to prevent clif)ping of the background planes. For example, if the 
pane was made to fit the height of the cubic display space, the 
front half of the ground plane would be cli[)f)ed by the bottom 
of the pane, as soon as the user would move his eye above the 
bottom of the pane. If you find that clipping still occurs, you can 
decrease tlie pane widtli to height ratio to, for example, 1:2. 

List ing 2: ViewCreation.c_ _ 

NcwViewPlanct Camera 

TQ3Caraera0bjcct NewViewPlaneCamera(void) 

I 

TQSStatus returnVal = kQ3Failure ; 

TQ3ViewPlaneCameraData perspectiveData: 

TQ3Camera0bject camera; 

// camcraLot sUion is on the z-axis 

TQ3Point3D from =10,0.51; 
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// view plane origin at world origin 

TQ3PoinL3D to = 1 0. 0. 0 1; 

TQ3Vector3D up = 1 0.0, 1.0, 0.0 }; 


float 

float 


paneWidth = kPaneWidth; 
paneHeight= kPaneHelghi; 


perspectiveDa ta.cameraData.placement.canioraLocation= 
from; 

perspectiveData.cameraData.placement.pointOfInterest= 
to; 

perspectiveData.cameraDa ta.placement.upVector=up; 

//’Ilic display space is I QuickDraw 3D unit deep. 

//We put the hither pane just in from of the display space... 
perspectiveData.cameraData.range.hither = from.z - 0.5; 


// and the yon plane just behind it. 

perspectiveData.cameraData.range.yon = from.z + 0.5; 


// use the full viewPort 

perspectiveData.cameraData.viewPort.origin.x = -1.0; 
perspectivcOata.cameraData.viewPort.origin.y = 1.0; 
perspectiveData.cameraData.viewport.width = 2.0; 
perspectiveData.cameraData.viewPort.height* 2.0; 


// the distance from the virtual camera to the view plane equals 
// the z-coordinate of the camera jxwilion, since the view plane coincides with 
// the xy plane, and the camera vector is parallel to the z-axis. 
perspectiveData.viewPlane = from.z; 

// the aspect ratio of these parameters should equal 
// that of Uie pimeWidth and paneHeighi. 

// I’or convenient calibration wc'vc made widthAtViewPlane = I, 

// so halfVl5dthAtViewPlane = 0.5 

perspectiveData.halfWidthAtViewPlane = 0.5; 
perspectiveData.halfHeightAtVicwPlane= 

0.5* paneHeight/paneWidth: 


// image centred around center of the xy plane 
perspectiveData .ceriterXOnViewPlane “ 0: 

perspectiveData.centerYOnViewPlane = 0; 

camera = Q3ViewPlaneCamera_New(&perspectiveData) ; 


centerYOnVicwPlane parameters. Tfie viewPlane parameter is the 
distance from the camera to the viewPlane. We can simply set it to 
the value of the z-ccxirdinate of the camera position. 'Phe 
centerXOnViewPlane and centerYOnViewPlane are set to the minus 
x-coordinate and the minus y-coordinatc of the virtual camera. This 
ensures that we’re always looking at an imaging area which is 
centrc*d around the world origin. As the cubic display space is also 
centred around the world origin, it dcx\s not .shift within tlie pane, 
even though the camera is translated without Ixing rotated. 


Listing iLViewPlaneCam _ _ 

Ad I usi VicwPlaneCamera 

TQ3Status AdjustViewPlaneCamera( DocumentPtr theDocument) 

1 

Point mousePosition ; 


TQ3Camera0bj ect 

TQSCameraPlacemcnl 

TQ3Point3D 

TQ3Vector3D 

float 

float 

float 


myGamera ; 

myCameraPlacement; 
from, to; 

up = 1 0.0, 1.0. 
viewPlane; 
centerX; 
centerY; 


0.0 1 ; 


TQ3Status status; 


TQ3Boolcan 


positionChanged; 


// If no comrollcr could be found 

// during initialization, fTrackcr was set to NULL. 

// In that ca.se we re using mouse contn)!. 

//This allows us to check whether things are working 
// alright without a tracker present. 


if (theDocument->fTracker = NULL) 

( 

GetMouse(6imousePosition) ; 
LocalToGlobal(&mousePosition) ; 


return camera ; 

) 

The code which adjusts the camera on every nullEvent is in 
Listing 3- Although MaeVRoom is meant to be used with a three 
DOF position-measuring device and its QuickDraw 3D driver 
(explained next month), wc do provide some code to couple the 
camera to the mouse. This allows you to .see the effect of the 
View Plane Camera without a tracker fxing present. Of course 
you can only benefit from the head-coupled perspective when 
you have a position-measuring device with three DOF. With a 
mouse the perspective will look strange and distoited, though 
you can try to move your head to find the eye position at which 
ihe perspective for the current mouse position looks correct. 

When a three DOF position-measuring device and its 
QuickDraw 3D driver are present, we first get the position of tlic 
tracker from the tracker object, lb this raw [xisiiion the calibration 
matrix is applied (Cilibralion is necessary Ixcause it is neither 
po.ssible to put the .sensor in the middle of the eye, nor tlie u^acker 
in the middle of the pane. We will discuss caliliration extensively 
next month). Now we can u.se the resulting position lo control the 
camera. To keep the camera jiarallel to die Z-axis wc make the 
point of interest the same as die camera position, with die only 
difference that the z-<:(X)rdinate is set to zero. Now we need to 
sjxcify which part of the imaging plane we wish to record. We do 
this by .setting the viewPlane, centerXOnViewPlane and 


// Set camera position ba.scd on mouse coordinates. 

// Since the mouse has only got two DOf we re 
// setting the Z-c{X)rdinate to a fixed value. 

// We have cho.sen to set it to 5.0 * the pane width, 

// which is a reasonable approximation of the observer-screen distance, 
from.x =(float)(raousePosition.h gScreenMiddle.h)/lO; 
from.y =(float)(mousePosition.v-gScreenMiddle,v)/lO; 
from.z =5.0; 

1 

else 

( 

// (iet the position from the tracker object. 

.status = Q3TrackGr_GetPo.‘;ition( 
theDocument'>fTracker. 

&from, 

NULL. 

Sipo.sit lonChanged. 

NIIT.L) ; 

// If it fails or doesn’t bring us a new position 
// we re not bothering with adjusting 
// the virtual camera, 
if ((status != kQ3Success) || 

(positionChanged = kQ3False)) goto bail; 

// apply the c'alibration matrix on the raw position 
Q3Point3D_Transform(&froin. 6rgCalibrationMatrix. &froni); 


// Set die point the camera I(X)ks al 

// the line of sight of the camera is always 

// parallel to the Z-axis, so wc can simply 

// set the Z-coordinaic lo zero. 

to.x = from.x; 

ro.y = from.y; 

lo.z = 0.0; 
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// l ill in the camera placement. 

myCameraPlacement .r.ameraLocation = from: 
myCameraPlacemeiiL. poi ntOf Interest = to; 
myCameraPlacement.upVector = up; 

//The di.stance to the viewPlanc is simply 
// the value of the Z*c(H>rdinate. 
viewPlane - from.z; 

//We re cutting out a piece of the viewPlanc 
// centered around |0,0,0}. 
centerX = -from.x: 
cenlcrY = -from.y ; 

// Work out the range of the hither an yon 
//This is to make sure we don’t get Z-buffer problems 
myRange.hither ~ from.z * 0.5; 
myRange.yon = from.z + 0.5; 

// Get the camera from the view 

Q3View_Gct.Camera (theDocuffient->fVlcw. &niyCamera); 

// Fill in the fields of the camera 

Q3Camera_SetPlaccmcnt (myCamera, &inyCaineraPlacement); 
Q.3ViewPlaneCamera_SetVif‘wPlane (myCamera, viewPlane); 
Q3ViewPlaneCamera_SetCenlcrX (myCamera. cenierX); 

Q3VicwPlaneCamera_SetCentery (myCamera. centerY); 

Q3Caniera_SetRange(myCamera, &myRange); 

// Dispose of the camera object 
Q30bject_Disposn( myCamera ) ; 

return kQ3Success ; 

ball: 

return kQ3Failure ; 


Using Your Head-Tracked Display 
How to Use MaeVRoom 

MaeVRoom allows the user to calibrate the tracker, load a 
3DMF model, display it inside a concave, cubic space and look ai 
it from different points of view by moving his head. If a position 
tracker and driver can l)c found, MaeVRoom starts with a 
calibration pr(K:edure. Please follow the on-scTcen instructions. 
'Hie user is asked to keep the sensor twice the width of the pane 
in front of the top-left corner of tlic pane and to press return. This 
process is then repeated for the bottom-right cximcr of the pane 
(Next month we will provide you with much more info on 
calibration, as well as a more accurate calibration method). If no 
position tracker and driver can be found, MaeVRoom switches to 
mouse control, and the calibration proc:edure is skipped. 

To create an undisturbed backdrop for the rendering, 
MaeVRoom hides the Finder and any other application by a 
window which covers the whole screen, and creates a 
QuickDraw 3D pane inside that window. The cubic space in 
which the model is displayed is formed by three .square polygons 
(Figure 8). Its center is at the center of the pane and the front- 
rear diagonal of its ground plane runs parallel to the z-axis. 

From the projection menu the user can choose between two 
different projection methexis called tlie Delft Virtual Window 
System (DVWS) (Figure 4) and Fish 'Fank VR (Figure 5). Please 
read the section '‘Inuoduction to Head-tracked Camera Methcxls” 
for an explanation of these terms. With the DVWS, the middle of 
tlie left-right diagonal plane of the cubic display space ap|X?ars to 
be pinned to the monitor .screen. With Fish Tank VR, the whole of 
the diagonal plane coincides with the monitor screen. 'Ihe left and 
right vertical edges thus appear to be sftick to the .screen. 
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Figure 8. A screenshot of the MacWoom application. 

When everything is up and running you will see a startis 
bar above the rendering pane. 'I’his status bar gives you the 
following information: 

• Frame count: The number of frames that have been 
rendered .so far. 

• Time. Tlie time which has elapsed since rendering the first frame. 

• 'Single frame'fps: This frame rate in frames per second is 
the inverse of the time it takes to render a single frame. It 
does not take into account the time it takes to complete 
other tasks, such as event handling and adjustment of the 
camera. Note that, depending on the complexity of the 

continued on page 42 
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continued from page 39 

model and the speed of the Mac, you may get figures 
exceeding the screen refresh rate. While the Mac can 
render the model at a frame rate greater than the screen 
refresh rate, it can never display the rendered images at 
such a rate. 

• Cumulative fps: This is the frame rate in frames per 
second calculated by dividing the elapsed time by the 
number of frames rendered since start up. This cumulative 
frame rate suffers from start-up overhead. Youll notice 
that it slowly increases. 

• Raw coordinates: These are the x, y and 2 coordinates as they 
come in from the driver application. 

• Calibrated coordinates: These are the x, y and z coordinates 
of the virtual camera. 

Where to Place the Sensor 

OK, so you’ve got a PowerMac with QuickDraw 3D, a 
three DOF tracker, a driver and MaeVRoom, and everything is 
calibrated. All you need to do now is to attach the sensor to 
the head in some way. You can choose between viewing the 
scene with one eye or with two eyes. Some people find that, 
in absence of stereo imaging, one-eyed viewing of the virtual 
scene results in a more convincing depth impression than 
two-eyed viewing. This may be because with two-eyed 
viewing there is a depth cue conflict between the 
stereoscopically perceived surroundings (Mac, monitor, table 
etc.) and the monoscopic virtual scene. A disadvantage of 
viewing the scene with one eye is that you either need to 
keep the other eye closed or wear an eye patcli, which means 
more headwear and thus discomfort. 

If you use one eye, try to mount the sensor as close to 
the viewing eye as po.ssible (Figure 9 and 10). Remember 
that we’re trying to establish the position of the eye. As we 
cannot mount the sensor in the eye we have to make do with 
mounting the sensor near the eye. As a consequence there 
will always be some amount of viewpoint dislocation. Since 
we’re using a sensor which provides only position and no 
rotation information we cannot accurately compensate for 
this dislocation as we do not know which way the iLser’s head 
is tilted. If you’re viewing with two eyes, you may wish to 
consider mounting the sensor between the eyes. In either 
case you could you use a headband or just the frame of a pair 
of spectacles. Before you mount the .sensor to headband or 
glasses, make sure that the orientation and position of the 
sensor is such that it stays within track of the base unit in the 
region in front of the monitor. 



Figure 9. The FreeD sensor mounted in the middle for two-eyed 
viewing (leftX and above the right eye for one-eyed viewing (right). 



Figure 10, The Dynasight reflector mounted in the middle for two- 
eyed tmmnng (left), and above the tight eye for one-eyed viewing 
(right). Note that the offset in the vertical direction (dy) differs. 


Trouble shooting 

What if it kind of works but you don’t find it really 

convincing? I’he following hints may give some improvement: 

1. Have you accurately followed the calibration procedure? If 
the sensor is not accurately calibrated the virtual camera does 
not correspond to the user’s head position. To the user this 
misalignment appears as distortion. You can check whether 
the system is properly calibrated by looking at the calibrated 
coordinate field in the status bar, and holding the sensor 
stationaiy in the following locations. The left edge of the 
pane should give x=-0.5 and the right edge x=0.5. As we’re 
working with a width:height ratio of 1:^2 the top edge of the 
pane should give 0.71 and the bottom edge -0.71. Holding the 
seasor in front of the monitor by the width of the window, 
should give a z-coordinate of z=l. Of course these figures are 
only approximate. It is unlikely that you will find exactly 
these values, but at least you can find out whether calibration 
is OK-ish or has gone completely haywire. If the values are 
off, restart MaeVRoom to calibrate the system anew. 

2. Is the frame-rate acceptable on your machine? Below 15 fps 
you’ll probably suffer from a lot of delay. Make sure you are 
limning with the QuickDraw 3D runtime extensions rather 
than the debug extensions as the latter are much slower. Try 
switching off the textures on the background planes by 
changing the conditional compiler .statement “#define 
TEXTURE 1” to “#define TEXTURE 0”. Try loading a less 
complex model with fewer polygons and fewer textures. Try 
running in thousands rather than millions of colors. Make 
sure that AppleTalk is inactive and that you don’t have any 
extensions active which cause noticeable interrupts, such as 
fax extensions. Anything which overlaps the rendering pane, 
either another window or the control strip will cause 
performance degradation. Remember that QuickDraw 3D 
does not like virtual memory. Your choice of geometry can 
have a considerable influence on frame rate. With the 
interactive Tenderer trimeshes yield the best performance, 
meshes the worst, with polyhedrons somewhere in between 
(Schneider, 1996; Zako et al., 1997). 3DMF Models can often 
be made to render significantly fa.ster by using 3DMF 
Optimizer (Pangea). Finally, if you are running without 
hardware acceleration and use a PCI PowerMac, consider 
adding an accelerator board. 'Fhere is lots of inlbrmation 
available on the QuickDraw 3D home page. 
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Conclusions 

In this month’s Part T we documenled the graphics-rclatcd 
aspects of the implementation of a head-tracked display on 
PowerMacintosh using QuickDraw 3D. A head-tracked display 
gives the user a depth impression of a 3D scene without the 
use of stereoscopy. We showed you how to use the View 
Plane camera to achieve a perspective projection which takes 
the user’s head position into account. We also showed you 
how to use the viewer application and how to lrou[)leshoot. 
In next month’s Part II we will have a look at the hardware- 
related issues of our head-tracked display. 
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Introducing QuickTime 3 


What’s new in the latest 
version of Apple’s flagship 
multimedia software 


Introduction 

On the 30th clay of the 3rcl month of 
this year, Apple released QuiekTime 
version 3, the latest and probably the most 
eagerly awaited version of its award¬ 
winning multimedia software architecture. 
QuickTime 3 provides dozens of features 
that are new or improved over earlier 
versions. Quick'rime now supports more 
than 30 industry-standard video and audio 
file formats, and it provides a host of new 
capabilities on both Macintosh and 
Wind(3ws computers. In this article, 1 11 
describe what T lake to be the major 
enhancements contained in QuickTime 3. 

Of course, it would take far more 
space than is available here to cover all of 
vvliat’s new in QuickTime 3. Instead, to 
borrow some terminology from the game 
of baseball, I’ll focus on the home runs and 
the extra-ba.se hits; you can investigate the 
solid line-drive singles yourself at the 
Quickl’ime 3 web site and in the 
developer documentation. See the 
References section at the end of this article 
for pointers to those resources. 

As you know, QuickTime comprises a 
numlxM- of media technologies, including 
synchronized sound and video, still 
graphics, sprite animation, text, music, 
virtual reality, and 3D imaging. Quickl’inie 3 


has added some exciting new capabilities, such as wired .sprites, 
vector drawing, and video effects, and has enhanced the 
interoperability of the existing technologies. Before discussing 
those innovations, let's begin by considering what’s new in 
QuickTime 3 for users and content developers, and what’s new in 
QuickTime 3 for the web. Tlien we can look at the goodies that 
Quicklime 3 provides for software developers. 

User-Level Software 

The typical user’s first experience with QuickTime 3 will 
probably involve one of three new pieces of software: a revised 
and expanded MoviePlayer application, an upgraded image¬ 
viewing application called PictureViewer, or the new QuickTime 
Plug-In for web browsers. As initially installed on either 
Macintosh or Windows computers, these three items are limited 
to “basic” operations. For example, the basic MoviePlayer 
application allows the user to open and view QuickTime movies, 
but does not allow editing or .saving those movies. The basic 
PictureViewer application exhibits similar restrictions: the user 
can open images and apply various tran.sformations to them 
(such as rotate and resize), but cannot save any modified images. 

A user can upgrade to QuickTime 3 Pro by registering across 
the net. Upgrading involves obtaining a registration number and 
then entering that number into a panel of the QuickTime™ 
Settings control panel. Once the registration number is validated, 
the MoviePlayer and PictureViewer applications are automatically 
upgraded to their Pro versions, which allow editing, saving, and 
many other operations on movies and images. Keep in mind that 
the “basic/Pro” distinction applies only to MoviePlayer, 
PictureViewer, and the plug-in: all other software (your 
QuickTime-savvy application, for instance) is able to take full 
advantage of the QuickTime APIs, which are fully functional 
even if the user does not upgrade to the Pro version. 

For content developers, QuickTime 3 provides a wealth of 
new capabilities. MoviePlayer Pro allows the content developer 
to perform sophisticated movie editing and to save edited movies 
using a wide variety of compression formats and .special effects. 


Tim Monroe <m()nr()e@apple.c()m> is a software engineer on Apple’s QuickTime team. He is currently developing .sample 
code for the new QuickTime 3 programming inlerDces. In his previous life at Apple, he worked on the Inside Macintosh team. 
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Apple has partnered with a number of other companies to 
provide new compression technologies for both video and 
sound. On Windows computers, QuickTime 3 f)rovides the Indeo 
codec from Intel. On both Macintosh and Windows computers, 
QuickTime 3 includes the Sorenson Video codec from Sorenson 
Vision, Inc. (which provides state-of-tlie-art compression 
technology giving extremely good image quality at a remarkably 
small data rate). Also included are cross-platform codecs from 
QDesign (which provides impressive music fidelity in as little as 
1 percent of the original file size) and QualCornm (whose Pure- 
Voice technology does very good compression on voice data). 
Finally, (QuickTime 3 includes the Sound Canvas instrument set 
for playing MIDI sound files and the OS Format extensions 
developed by Roland Corporation. 

QuickTime on the Web 

QuickTime 3 includes a new, more powerful plug-in for the 
Netscape Navigator and Microsoft Internet Explorer web 
browsers, on both Macintosh and Window's. 'Phis plug-in 
supports the display and control of all of QuickTime’s digital 
formats directly in the browser window. The brow^ser plug-in 
provides several other important new^ features, including 
QuickTime Streaming and automatic selection of media based on 
the user’s connection speed. 

Quick'Pime Streaming is a feature of the QuickTime Plug-In 
that allows QuickTime movies to begin playing before the entire 
movie has been downloaded to the user’s macliine. The [)lug-in 
waits until it has enough of the movie downloaded that it is 
confident that the remaining movie data wall be downloaded by 
the time it’s needed. The result is that the user spends less time 
waiting and more time interacting with the digital content. 

(Jiiick'Pime Streaming also works for non-linear QuickTime 
media, such as QuickTime VR panoramas and objects. The only 
“gotcha” for VR content is that the movie must be specially 
Ilattened for streaming web playback. Content developers will 
need to install the QTVR Flattener extension (available at the 
QuickTime wei) site) and then export a flattened movie using 
MoviePlayer Pro. When exporting flattened V’T^ content, the 
developer can include a lower-resolution preview track (or even 
an ar[)itrary image file) that downloads veiy quickly and provides 
the user with a passable preview of the VR movie. If no such 
preview track is included in a web-flattened VR movie, the 
QuickTime Plug-1 n substitutes a grey-on-black grid (rather like the 
Star Trek holodeck background) for any data not yet downloaded. 

QuickTime 3 provides a second w'ay to address the web 
bandwidth problem with its support for “multiple data rate” 
movies. Here the idea is to tailor the data to be downloaded to 
the user’s connection speed (which can be set in the QuickTime™ 
Settings control panel). The content developer accomplishes this 
by creating a single QuickTime reference movie, which contains 
references to several other QuickTime movies of vaiying sizes 
and resolutions. When a user chooses to view a reference movie 
embedded in a web page, the Quicklime Plug-In automatically 
selects the target referenced movie best suited for the user’s 
connection speed. For example, if the user has a LAN or T1 
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conncclion lo ihc InlcrncL, the plug-in .selects the highest quality 
movie referenced in the reference movie. If the user has a slow 
modem connection, say l4.4KBaud, the plug-in instead chooses 
a smaller, lower-resolution movie, probably also with the audic3 
and video compressed to a greater degree (with an attendant loss 
of quality). In this way, the QuickTime Plug-In delivers the digital 
content best suited for a specific user, automatically and 
completely transparently to the user. 

Of course, the QuickTime Streaming feature works with 
multiple data rate movies too. Once the plug-in has decided 
which referenced QuickTime movie to download, the data is 
streamed as described above. 

QuickTime Video Effects 

QuickTime 3 provides an extensible architecture for 
applying video effects to single images or video tracks (“filters”), 
or to pairs of images or video tracks (“transitions”). QuickTime 3 
includes an implementation of the 133 standard transitions 
defined by the Society of Motion Picture and Television 
Engineers (SMPTE), as well as some additional effects defined by 
QuickTime. The SMP'FE effects include transitions like a simple 
explode (where the first image is pushed outward by the .second 
image) and a radial swipe (where the first image is covered over 
by the second image in a clockwise turn). The QuickTime effects 
include a veiy nice “cro.s.s fade” or “di.s.solve” (which uses a 
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smooth alpha blending from the first image to the second) and a 
nifty "film noise” filter that makes a video track look like old, 
faded, dusty, and scratched film (sec Figure 1). 



Figure 1. The film noise filter applied to a movie frame. 

QuickTime 3 even defines several video effects that operate 
on no source images or video tracks at all. For instance, you can 
use the fire effect to generate a real-looking fire, and you can use 
the cloud effect to render a wind-pushed, moving cloud. With 
zero-source effects, the idea is that you will want to composite 
the effect onto some other image or video track. 

What’s intere.sting about all these effects is that they use 
extremely little data to achieve the desired visual effect. The data 
describing an effect is stored in a video track, and the actual 
effect itself is generated in real time as the movie that 
incorporates the effect is played. For instance, a movie track that 
sj^ecifies the fire effect is only about 200 bytes in size, but when 
played generates a real time, non-repeating, dynamic effect. 

Filters and transitions are implemented in the general 
QuickTime architecture as image decompressor components. 
One thing this means is that you can use filters and transitions 
anywhere you might u.se a decompressor, not only in 
connection with QuickTime movies. You can just as easily 
apply a transition between two arbitraiy images (perhaps 
contained in two offscreen graphics worlds). I’ve .seen this 
capability u.sed to add QuickTime video effects as transitions 
between QuickTime VR nodes. The default behavior of 
QuickTime VR is simply to jump from one node to the target 
node. It’s mtich nicer to render .some video effect, .say a nice 
sm(K)th di.s.solve, when moving from node to node. 

Tlie faa that effects are implemented as decompressors also 
meaas that it’s relatively easy to construa your own custom effects 
and to make them available to any appliaitions lliat sup|X)rt 
QuickTime. Apple even |:)rovides source code for a sample effect that 
you can use as a starting point for your own effects development. 


QuickTime Veceors 

QuickTime 3 provides a pleasant surprise in its support for 
vector-based drawing. QuickTime vectors are mathematical 
descriptions of images, rather like PostScript images. An image tfial 
is dc*scTilx:d using QuickTime vectors can be resized with no 
quality loss in the image. More importantly, the desc'ription of an 
image using QuickTime vectors is almost always significantly 
smaller than a [)iimap description of the same image (even when 
tlie bitmap is compressed). In addition, QuickTime’s vector-based 
drawing supports a relatively fast form of antialiasing that 
determines the color of anlialia.sed pixels based on the curve 
calculation itself mther than the .standard technique of drawing the 
image at higher resolution and scaling it down. For these reasons, 
Quicklime vectors provide a welcome and powerful addition to 
the QuickTime family of digital media. 

A QuickTime vector is roughly the same as a QuickDraw GX 
path object, which is a connected series of straight lines and 
curves. Using paths, you can define pretty much any geometric 
shape, from points and lines, to polygons, curves, and arbitrary 
concatenations of lines and curves. Quickfime vectors also 
support the standard QuickDraw GX drawing styles (for instance, 
pen widths and joins at corners) and inks (sup|X)rting many color 
spaces and image transfer modes). Indeed, the correspondence 
between GX paths and QuickDraw vectors is so close that you 
can easily convert exi.sting GX data into QuickTime vectors using 
an image transcoder included with QuickTime 3. 

A QuickTime vector image is described by a set of paths, wliich 
are ordered series of atoms in a QuickTime atom c:ontainer. (This 
set of paths is called a vector data stream.) The atom container is 
stored in a movie file as a media sample in a video track. To render 
a patli, the QuickTime vector codec traverses the atoms in the atom 
container, in the order they appear in the atom container. A 
particular atom may specify a palli (in which case the veaor codec 
draws tlic path using the cuirent drawing attributes) or a drawing 
attribute (in which c'ase tlie vector ccxlec sets that attribute as the 
default drawing attribute of its type). QuickTime 3 defines a large 
numlx.T of vector atom types, mast of which correspond to 
QuickDraw GX drawing styles. Quickl'ime 3 adds .support for 
.several atom types not suppoiled by GX, including gradient atoms, 
antialiasing atoms, and minimum bit depth atoms. 

Wired Sprites 

QuickTime 2.5 introduced the Sprite Toollx)x, a set of data 
types and functions that you can u.se to add sprite-based animation 
to an application. A sprite is simply one image from a finite .set of 
images. You can animate the sprite by changing iLs spatial 
properties (its matrix, its layer, its visibility, its graphics mode, and 
so on) or by replacing it with another image from that set of 
images. Sprite animation is analogous to traditional cell animation 
(which is used to create many cart(X)ns). 

One of the ccxilest new features of QuickTime 3 fs support 
for w'ired sprites, or sprites that react to mouse (and other) events 
and that have various actions attached (or “wired”) to llicm. In 
effect, the user can now click on sprites and initiate certain actions 
with tliose clicks. By using wired sprite tracks in a movie, you can 
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acid a level of interactivity previously unavailable in QuickTime. 
For instance, you can use wired sprites to control various aspects 
of movie playback, such as ilie volume and balance of a sound 
track, or the graphics mode of a video track. Wiili a mcxlicaim of 
cleverness, you could use wired sprite tracks as the entire 
graphical user interface for your application. 

Figure 2 illustrates a simple wired sprite movie. This movie 
contains six sets of sprite images: two penguins and four buttons. 
Clicking on tlie rightmost penguin causes the other penguin to 
waddle down to the right and back again, in a loop. I’he 
rightmost penguin moves straight down until reaching the 
bottom of the movie, at which time he (she?) jumps back to the 
top and starts over. The buttons, which appear only if the mouse 
is over a button or within the waddling penguin, control the 
movements of the waddling penguin. 



Figure 2. A simple wired sprite movie. 


Wired sprites can respond to several kinds of events. 
Primarily they respond to mouse events (mouse downs, mouse 
ups, mouse enters, and mou.se exits), but they can also receive 
and react to idle events and to events generated when the key 
frame containing the sprite data is first loaded. In response to any 
of these events, a wired sprite can effect changes in one or more 
targets (including itselO. A target is always a sprite, a movie track, 
or the movie itself. QuickTime 3 defines a large numlx:r of 
actions that a wired sprite can initiate in its target. For instance, 
a wired sprite can cause a target sprite (po.ssibly itself) to change 
the index of the displayed image. This is how you might make a 
sprite button appear to be pressed, by having a clicked-on sprite 
change its own image index. 

QuickTime VR 

QuickTime 3 includes an upgraded version of QuickTime 
VR, version 2.1. Tliis new version provides .several important 
enhancements to the previous major release, QuickTime VR 
version 2.0 (introduced for the Macintosh in January 1997). From 
a user’s point of view, Quic kTime VR 2.1 provides improved 
image quality and smoother panning, tilting, and 7.(X)ming. In 
addition, QuickTime VR movies can be embedded in web pages 
and reaj) all the benefits provided by the QuickTime Plug-In, 
including QuickTime Streaming and URL linking from VR hot 


MkLinu, 

Microkernel Linux for the Power Macintosh 
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MkLinux is a complete system, based on Linux 2 and the 
Mach 3 microkernel. It includes development tools (gcc, 
gdb, perl,...), X11R6.3, and hundreds of other commands. 


MkLinux builds and runs most In tel-based Linux software. 
It works efficiently and reliably on a wide range of Power 
Macintosh platforms. Visit Apple Computer's MkLinux web 
site (www.mklinux.apple.com) and Prime Time Freeware's 
web site (www.ptf.com) to find out more about MkLinux! 

MacPerl: Power and Ease 

MacPerl is a robust and powerful port of Perl 5 to the Mac. 

It runs under the Finder and MPW, supports Apple Events 
and Toolbox calls, and is generally quite nifty! For details 
on MacPerl and associated products (book, CD, etc.), visit 
the MacPerl Pages (www.ptf.com/macperl). 


Prime Time Freeware info@ptf.com 

370 Altciir Way, #150 (408) 433-9662 

Sunnyvale, CA 94086 (408) 433-0727 fax 


spots to other web pages or to multimedia files. Moreover, 
QuickTime VR movies can be compressed using most of the new 
ccxiecs supported by QuickTime 3. Many VR content developers 
have discovered tliat tlie Soreason codec, in particular, provides 
a very compact file with minimal loss to tlie image quality. 

The application programming interfaces provided by 
QuickTime VR 2.1 are virtually identical to those previously 
supported in version 2.0. (See Monroe and Wolfson, 1997, for an 
introduction to the QuickTime VR application programming 
interfaces.) The main difference is that version 2.1 now provides 
support for both Macintosh and Windows platforms. A number 
of other minor changes were made, including renaming a 
handful of functions and data types, adding a few utility 
functions (for instance, QTVRGelHotSpotType), and expanding 
the user interface options for object nodes. Also, you can now 
request that the Quicklime VR movie controller display a custom 
button in the c:ontroller bar, and you can intercept clicks on that 
button and perform actions in resf)onse to tluxse clicks. 

Cross-Platform Support 

Let’s consider now what is undoubtedly the game-winning 
grand slam in QuickTime 3: with very few exceptions, the 
QuickTime application programming interfaces operate 
identically on both Macintosh and Windows computers. Before 
QuickTime 3, Windows support was limited primarily to movie 
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playback using a movie controller. The application programming 
interfaces provided by the QuickTime for Windows prcxluct were 
different from the QuickTime APIs on the Mac; in particular, the 
Windows APIs did not support creating or editing movies, and 
they did not support playing movies without using a movie 
controller. With the advent of QuickTime 3, these limitations 
have been entirely removed, and the Macintosh and Windows 
versions of QuickTime 3 exhibit virtually complete feature parity. 
In short, if you can do it on the Mac, chances are you can do it, 
using the same source code, on Windows NT or Windows 95. 

Pet’s kK)k at a few source code examples to appreciate tliis 
fully. Listing 1 shows a simple routine that uses QuickTime 
functions to copy a video track from one movie into another movie. 


Listing 1: Copying a video track from one movie to another 

OSErr CopyVideoTrack (Movie theSrcMovie, Movie theDslMovie) 

I 

Track mySrcTrack. myDstTrack; 

Media mySrcMedia, myDstMedia; 

Fixed rayWidth, myHeight; 

OSType myType: 

ClearMoviesStickyError0; 

// gel the first video track in the source movie 

mySrcTrack = GetMovielndTrackType(theSrcMovie. 1, 

VideoMediaType. movieTrackMediaType): 
if (mySrcTrack = NULL) 
return(paramErr); 

// get the track’s media and dimensions 
mySrcMedia = GetTrackMedia(mySrcTrack); 

GetTrackDiraensions(mySrcTrack, &myW1dth, 6irayHeight) : 

// create a destination track and media 

myDstTrack = NewMovieTrack(theDstMovie. myWidlh, myHeight, 
GetTrackVolume(mySrcTrack)); 
GetMediaHandlerDescription(mySrcMedia, &myType, 0, 0): 
myDstMedia = NewTrackMedia(myDstTrack, myType, 

GetMediaTimeScale(mySrcMedia). 0. 0): 


// copy the entire track 

InscrtTrackSegment(mySrcTrack, myDstTrack. 0. 

GetTrackDuration(mySrcTrack), 0); 
CopyTrackSettings(mySrcTrack, myDstTrack): 

SetTrackLayer(myDstTrack, GetTrackLayer(mySrcTrack)); 

return(GetMoviesStickyError0): 

) 


As you can see, all the functions c:alled in Listing 1 are 
standard Quick'Lime functions. Because the QuickTime APIs are 
identical on both platforms, the Copy Video! rack routine will 
compile and run on both Macintosh and Windows computers 
running QuickTime 3. 

Consider next the function defined in Listing 2, which 
prompts the user to open an image file and draws the image into 
an offscreen graphics world. (Note that error-checking has been 
removed from this routine.) 

Listing 2: Drawing an image file into an offscreen 
graphics world 

void GetPictureAsGWorld (short theWidth, short theHeight. 
short theDepth, GWorldPtr *theGW) 

( 

SFTypeList myTypeList; 

StandardFileReply myReply; 

GraphicsImportComponent myimporter “ NULL; 


Rect myRect; 

PixMapHandle myPixMap = NULL; 

// have the user select an image file; kQTFilcTypcQuickTimclmage means any image 
// file readable by GetCiraphicsImporlerl'orFiic 
myTypeList[0] = kQTFileTypeQuickTimelmage; 
StandardGelFllePrevifiw(NULL, 1, myTypeList, &myReply); 
if (!myReply.sfGood) 
goto bail; 

// get a graphics importer for the image file 

GetGraphicsImporterForFile(&myReply.sfFile. ^mylmporter); 

// set the size of the GWorld and allocate a new GWorld 
MacSetRect(&myRect, 0. 0, theWidth, theHeight); 
NewGWorld(theGW, theDepth, &myRect, NULL, NULL, OL); 

myPixMap = GetGWorldPixMap(*lheGW); 

LockPixels(myPixMap); 

// draw the picture into the GWorld 

GraphicslmportSeiGWorld(myimporter, *theGW. NULL); 
GraphicslmportSelBoundsRect(myimporter, &myRect); 
GraphicsImportDraw(mylmporter); 

bail: 

if (myimporter != NULL) 

CloseComponent(myimporter); 

I 


Notice that the GetPictureAsGWorld function defined in 
Listing 2 iLses not only QuickTime functions, but also Standard 
File Package functions and QuickDraws offscreen graphics 
world functions. Nonetheless, this routine compiles and runs 
fine, on both Windows and Macintosh computers. On Windows, 
the StandardGetFilePreview call is “translated” into a call to the 
Windows API function GetOpenFileName, which displays and 
manages the Windows equivalent of the standard file-opening 
dialog. In fact, the Windows implementation of 
StandardGetFilePreview enhances the stock Windows dialog box 
by adding the ability to view and create movie previews in the 
dialog box. Figure 3 shows the Macintosh version of the dialog 
box displayed by StandardGetFilePreview, and Figure 4 shows 
the Windows version of the same dialog box. 



Figure 3. The dialog box displayed by SlandardCetFilePreview 
on Macintosh computers. 


Interested in writing for the magazine? 
Download a writer's kit from 
<http://www.mactech.com> 
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Figure 4, 'I he dialog box displayed by SlandardGelFilePreview 
on Windows computers. 

Consider finally the (xxle snippet shown in Listing 3, which 
is typical Macintosh code for displaying and managing a mocLil 
dialog box with a pop-up menu in it. As you can see, this code 
uses the Dialog Manager, the Control Manager, and the Window 
Manager. Indirectly, through the GelNewDialog function, it also 
calls the Kesource Manager. And yet, believe it or not, this code 
compiles and runs under Windows. 

Listing 3: Displaying a dialog box with a pop-up menu 

// gel ilie dialog that lets the user .select an effect component 

myDialog ^ GetNewDialog(kDialogTD, NULL, (WindowPtr)-1); 

SetDialogDefaultItera(myDialog, kScleeiButtonOK): 

GetDialogTtom(myDialog, kPopUpID, NULL, &inyItemH, NULL): 

SerCotU rol Value((ControiHandie)mylteinH, gCurrEffect.) ; 

// now show the dialog 
MacShowWindow(myDialog); 

MacSetPort ((GrafPtr)niyDialog): 

do I 

ModalDialog(gModall!iiterUPP, imyltem); 

1 while (myitem != kSelectButtonOK); 

// gel the currtrnl value of the pop-up menu 

gCurrEffect “ GetControlValue((ControlHandle)myltemH): 
DisposeDialog(myDialog); 

I low far can you go using the Macintosh Toollx)x and OS AI^Is 
on Windows? In otlier words, ju.st how extensive is the ctdss- 
platform support provided by QuickTime 3? SulTice it to say, that T 
have SLicce.ssfully ported to Windows, with very little modification, 
code that calls the Macintosh File Manager, Memory Manager, 
Window Manager, Dialog Manager, Control Manager, Menu 
Manager, Sound Manager, Kesource Manager, Gestalt Manager, and 
others, in addition to tlie c'ort^ Quick! nne Media Layer technologies 
(Quickrime, QuickTime VR, and QuickDraw 3D). Apple even 
provides Windows versions of the developer tcxils Re/ and DeRez 
(plus a few Window.s-spec'ific resource tools). 

'lb me, this is no less tlian amazing. Over the pa.st few months, 
T have Ix^en continually impiessed at how C'lLsy it is lo gel existing 
QuickTime (xxle working in a Windows environment. Certainly not 
all of that cckIc could be ported unchanged. 'Lhere are important 
architectural differences Ixitween the Macintosh and Windows 
platforms (the event/message handling mechanisms and the 
endianness of multibyte data are gcxxl examples). Moreover, tliere 
are name-space collisions that ncod to Ix^ addne.ssed (for instance, die 


Windows Al! includes a .ShowWindow function, so the Macintosh 
function was renamed as MaeShowWindow; see Listings 2 and 3). 
Nonetheless, the Quickl'ime 3 engineers have done a marvc^loiLs job 
of making it pcxssible to write once and deploy crcxss-jilati'orm. 

It’s important to keep in mind, however, that QuickTime 3 for 
Windows Ls not intended primarily as a general-purptxse porting 
library for getting any Macintosh ccxJe at all to run under 
Windows. Radier, it is intended as a means of making QuickTime 
and related APIs work the same on all platforms that Quick'rime 
sup|X)rts. In general, you’re better off using standard Windows 
APIs to disj)lay and manage user-interface elements like windows, 
menus, and modeless dialog lx)xes, and to handle the basic flow 
of me.ssages in your Windows ap|ilications. 

Devew)per Support 

Apple has spent considerable resources to provide high- 
(juality developer dcxTimentation describing the new and revised 
features of QuickTime 3- Indeed, the documentation for the new 
and revised features of QuickTime alone (that is, not including 
QuickTime VR, QuickDraw 3D, or the sound teclinologies) runs to 
well over 1(X)0 printed pages! 'Lhis tome has been thorouglily 
reviewed by the key engineers and by the quality assurance teams 
to verify that the infomiation is clear, correct, and useful. 

Along with the main Quick'Pime 3 documentation, Apple 
provides several otlier dtxumenls taigeted at specific audiences. It 
contracted Stephen Chemicoff (autlior of the well-known Macintosh 
Reix'aled scM'ies of Ixxiks) to write an intrcxluction to QuickTime 3 
for Windows [)rogrammers, which is designed to help Windows 
developei’s understand the MacinUxsh concepts that underlie much 
of ihe QuickTime Al^ls (.such as offscreen graphics worlds, handle- 
Ixiscel memory management, and so forth). Apple has also collceicd 
the Inside Macintosh dexumentation for the principal crcxss-platfbnii 
!<x)llx^x and (3S Managers into a useful lxx)k Mac OS for Wimknvs. 
In all, the complete develojx^r dcx'unientation posted on the 
QuickTime 3 web site occLipies over 6,5(X) HTML pages. 

'rhe QuickTime 3 software development kii also includes 
extensive .sample code that illu.strates how to use many of the 
new and improved features of Quick'Lime 3. This source code is 
virtually all cross-platform, so you can compile and am the 
sample ccxle for Quick'Lime video effects, wired s|)riles, and 
vector drawing (to name only a few of the samples) on both 
Macintosh and Windows comf)uiers. 
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Network Services Location Technology 


How the NSL Technology 
Can Benefit Your Application 


Introduction 

When Apple inlroduced the Chooser 
and AppleTalk, they allowed users 
unprecedented ease-of-use in browsing for 
network services such as printers and file 
servers. With the introduction of the 
Network Services Location (NSL) 
Technology, Apple is bringing that same 
ease-of-use to the Internet. With NSL users 
have ihe ability to browse through Internet 
services such as FTP and MiTP via TCP/IP 
in the .same way they have traditionally 
brow.sed for AppleTalk .services using the 
CluKxser. By adopting this technology, 
a|)plications can provide a more intuitive 
and convenient method for users to access 
network services. 

The NSL Technology is compo.sed of a 
Manager and a set of plug-ins that gather 
data via particular network protcKoIs (such 
as DNS). The NSL Manager provides a 
single API across any number of resource 
discovery protocols, and by developing 
additional plug-ins, new methods for 
re.source discovery can be added with no 
additional work on the part of the 
application developer. In this article we 
will prCvSent the NSL technology and show 
you, the developer, how to incorporate it 
into your next project. 


What is NSL? 

'Hie Network .Services Location Manager provides a protcxx)!- 
independent way for applications to discover available network 
.services with minimal network traffic. The NSL Manager provides: 

• AppleTalk-like ease-of-use for the dynamic di-scovei-y of 
traditional and non-traditional network .services. 

• Support for accepted and propo.sed indu.stry standards, 
including Domain Name Service (DNS) and Service LocTition 
Protocol (SLP). SLP is an emerging .standard (see RFC 2165) 
for registering and finding Internet .services dynamically. 

• A flexible, expandable architecture that can be easily 
leveraged by client and server applications. 

A variety of applications can benefit from NSL technology. 
Chills to the NSL Manager can make these applications more 
intuitive and easier to u.se. For example: 

• In.stead of requiring the u.ser to lype a URL to locate a web 
.server, a brow.ser application that calls the NSL Manager could 
have an “Open Location” command that polls a network for 
HTTP servers and returns a list of URLs in the browser 
window from which a particular URL can be .selected. 

• (x)llalx)raLion .software, such as a video conferencing .server 
could regi.ster itself as an available .service on the corporate 
Intranet. Ihe u.sers of client video conferencing .software 
could then .search the Intranet for available conferences and 
join a particular conference without having to remember a 
ciyptic URL or IP addre.ss. 

Using NSL 

The NSL Manager acts as an intermediary between the 
providers of network .services and applications that want 
information about thcxse .services. Service applications regi.ster 
ihem.selves with the NSL Manager and which then acts through 
NSL plug-ins to perform the actual .searches. The NSL Manager 
can pass requests from applications to any plug-in that 
implements the NSL Manager API. 


The authors of this ankle are iiienil^ers of the Network Services LcKation Project Team at Apple Computer, Inc. 
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Cross-Platform C++ 

OOFILE and AppMaker keep your options open. 

http://www.highway1.com.au/adsoftware/crossplatform.html 

Experienced cross'platform developers have recommended for years the best way to get true native loo k~andfeel is to factor 
out your application logic and develop interfaces separately on each platform. With the AppMaker Code Generator for 
Windows this common strategy is now automated. Generate PowerPlanf (or other) for your MaCinterface and the 
industry-standard MFC for Windows'^. 

Even better, with our PowerPlant to MFC Portability Kit, included free with the generator, much of your existing 
PowerPlant code will compile directly under Windows. Remember, AppMaker can import screens from current source 
right now to start generating a Windows version, no need to suffer through re-drawing each dialog. 


An NSL pkig-in is an extension that makes itself available to 
the NSL Manager when the NSL Manager is initialized, but resides 
in memory only when it is responding to an application’s lookup 
request. I’he Extensions Manager can be used to enal)le and 
disable individual NSL plug-ins. When the NSL Manager is 
initialized, each NSL plug-in provides the following information 
to the NSL Manager: 

• The types of sei*vices the plug-in can search for, such as 
and FTP. 

• Tlie protocol the plug-in uses to conduct searches, such as DNS. 

The NSL Manager will be available on all PowerPC-based 
computers that run the Mac OS release code-named Allegro or 
later. The first release will be accompanied by two NSL plug-ins: 
DNS and SLR Additional NSL plug-ins may also become available 
from Apple Computer or third-party develo]:)ers. 

Figure 1 illustrates the relationship between applications, 
the NSL Manager, and NSL plug-ins. 



NSL 

plug-in2 


R43port:ftfl<w I 


Figure L The relationship betxveen the NSL Manager, 
NSL plug-ins, a? 2 d Applications. 


To search for network ser\dces, an application opens a 
session with the NSL Manager using NSLOpenNavigationAPl: 

status = NSTiOpenNavigat ionAPI( ficgOurClientRef ); 

Then it must prepare three data values that are used as 
parameters to the NSLStartServicesLookup function: 

• A recjuest parameter block that describes the services you 
want to look for. 

• A lookup request that describes how you want results to be 
returned to you. 

• A neighlx)rhood that describes the vimial “geographic” scope 
of the search. 

Creating the Reqijf.st Parameter Block 

To create a request parameter block, your application first 
makes a seiwice list that specifies the services to be searched for 
using NSLMakeNewServicesList and then pass the service list and 
any attributes to NSLMakeRequestPB. For example, to search for 
H'Tl’P and LTP services, you would do something like this: 

serviceList NSLMakeNewServicesList( “http,ftp” ); 
iErr.theErr = NSLMakeRequestPB( serviceT.ist, .&ncwDaLaPLr); 

Tn the call to NSLMakeRequestPB, your application can use 
the attribute parameter to specify a string that is to be used to 
narrow the scope of the search. For example, if the attribute 
parameter is “Web Sharing,” the search results will include only 
those Personal Web Sharing HTTP seiwices that have registered 
with “Web Sharing” as an attribute. 


Want to suggest an article for the 
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CRliA'riNG THE LOOKXIP REQUEST 
To create a synchronous lookup rc(|ucsl, your application 
calls NSLPrepareRequest like this: 

iErr - NSLPrepareRequesl( NUU.. NULL, gOurClientRef. 
&ourRequestRef. buffer, bufLen, 6fOurAsyncTnfo ); 

To create an asynclironous lookup request, your application 
calls NSLPrepareRequest like this: 

iErr = NSLPrepareRequest( notifierPtr, NULL. gOurClIcntRef, 
^ourRequeslRef.buffer. bufLen. &ourAsyncInfo ); 

When you call NSLPrepareRequest, you can specify NULL as 
the value for the notifier parainclcr (the first parameter in the first 
call above), if you want to wait for search results to be returned 
(synchronous mode). If instead, you want the NSL Manager to 
call your notification routine wiien search results are ready to be 
returned (asynchronous mode), specify a pointer to your 
notification routine. In the second call alx)ve notifierPtr is a 
procedure pointer to the client's asynchronous notifier. 
rhe other parameters to the NSLl^repareRequest fundion are: 

• contextPtr, which you can use to specify contextual 
information about this l(K)kup. 

• theClient, which is a value that your application received 
when it opened a with the NSL Manager. 

• ref, which on output is a pointer to the search request that 
NSLPrepareRequest will create. 

• bufPtr, which is a pointer to the buffer in which search results 
are to be placed. 

• bufLen, which is the length of bufPtr. 

• infoPtr, whic:h is a structure that contains values, such as a 
maximum search time and the interval at which NSL Manager 
is to return search results, that control how the search will Ix^ 
conducted. Your apfdicalion can change the default values 
before it starts the .search. 

Creatinc; the Neighborhood 
To define the virtual “geographic” boundary of the .search, 
your application calls NSLMakeNewNeighborhood. You can 
explicitly specify which a neighborh(X)d, for example apple.com. 
In the following example, the application creates a 
neighborhood whose boundary is apple.com. 

neighborhood = NSLMakeNewNeighborhood(“apple.com”. NULL ): 

Or, you can use the default neighborhood: 
neighborhood * N.SLMakeNewNeighborhood( NULL ); 

Starting the Lookup 

Once your application has created the recjuest parameter 
block, the l(X)kup re(|uest, and the neighlx)rho(xi, it calls 
NSLStartServicesLookup to .start the search: 

iErr = NSLStartServicesLookup( ourRequestRef, neighborhood, 
newDataPtr, ourAsyncTnfo ); 


The parameters to the NSLStartServic'es function are: 

• ref, which is the search request created when your 
application called NSLPrepareRequest. 

• neighborhood, which is the neighlx)rho(xl value created 
earlier by calling NSLMakeNewNeighborhood. 

• requestData, which is the reque.st parameter block created by 
calling NSLMakeRequestPB. 

• asyncinfo, which is the structure that contains values that 
control the way the NSL Manager returns .search results, 
obtained by previously calling NSLPrepareRequest. 

Continuing the Lookup 

If the NSLStartServicesLookup was called .synchronously, 
NSLStartServicesLookup returns after having placed the first 
lookup results in the results buffer field of asyncinfo. If 
NSLStartServicesLookup was called asynchronously, the N.SL 
Manager places the first lcx>kup results in the results buffer and 
calls your application’s notification routine. Your application 
copies the re.sults and calls NSLContinueLookup, which continues 
the lookup and returns more lookup results in the results buffer. 
Your application continues to call NSLContinueLookup until all of 
the re.sults have been returned. 

Conclusion 

'Lhis article has provided a brief overview of NSL. For more 
detailed information on the NSL technology, API and .sample 
User Interface recommendations, please refer to the Network 
Seixices Location Manager Developer’s Kit Documentation 
Icxated in the July issue of the Mac OS SDK CD distributed by 
Apple Computer, Inc. 
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you tearing out your hair for days? 

Found a critical piece of information 
somewhere so obscure that no 
sane person would consider looking there? 
Have an unanswered programming question 
so important that you think the world would 
want to know the answer as well? 

Need some beer money? 

Want your friends to see your 
name in print? 

Tell us about it! Write it up and send it to 
<tips@mactech.com>. We pay $25 for each tip 
published, and $50 for the Tip of the Month. 


52 


NirrwoRK Skrvices Location Technology 


MacTech • July 1998 













TOOLS OF 
THE TRADE 


by Stefan Sinclair 
Edited by Peter N Ixium 


A Tour of Sprite World 


A Review of the SpriteWorld 
Animation Library 


Game Sprockets (DrawSprocket in particular). This article will 
introduce one such library, SpriteWorld, and show you how to 
use it in your applications. 


Most of’ today’s computer games fall 
into one of two categories, based on their 
graphics model: games with two 
dimensional, scrolling graphics, or those 
built on a three dimensional graphics 
system. While the growing power of 
home comj)uicr systems has allowed an 
explosion of new 3-0 based products in 
recent years, 2-0 games sucli as 
Command & Conquer and WarCraft 
remain a popular .segment of the 
computer gaming market. A large 
percentage of these 2-0 games employ 
what is known as “sprite animation” — 
the use of graphic objects consisting of a 
number of pLxcl-map images shown in 
rapid succession to simulate movement 
on the screen. 

To accomplish sprite animation on 
the Macintosh, you can either develop 
your own sprite animation code from 
scratch (which can be a time consuming 
endeavor) or make use of one of a 
number of existing Mac OS sprite 
animation libraries available to the Mac 
OS developer. Popular sprite animation 
libraries include SpriteWorld, the Sprite 
Animation Toolkit (SAT), and Apple’s 


WllAT IS SpRJTIiWORLD? 

SpriteWorld was originally developed in the early 1990s 
by Tony Myles as a library of C routines and special pixel 
blitters (cu.stom high speed drawing routines) to implement 
fast, smooth sprite animation on the Macintosh. In 1996, Karl 
Bunker and Vern Jensen added a number of their own 
enhancements to the original SpriteWorld, including the 
ability to have a scrolling animation, tiled backgrounds and 
many new 680x0 and PowerPC blitters and released the new 
package as SpriteWorld 2.0. Shortly thereafter, a Pa.scal 
interface to SpriteWorld was released, as well as a 
C++/()bject-based version of SpriteWorld. There is even a 
version that builds under X-Windows and Win95/NT syvStems. 
SpriteWorld remains actively supported; at the time of this 
writing a new version (2.1) is undergoing beta testing. The 
source code remains freely available, and comes complete 
with API documentation as well as .several samf)le i)rograms. 
The current version of SpriteWorld requires a Macintosh witli 
Color QuickDraw and System 7 or higher. 

The SpriteWorld API is built around four basic data 
structures: S|)riteWorlds, SpriteLayers, Sprites, and Frames. The 
SpriteWorld is at the top of the hierarchy, driving the animation 
and providing the means with which to display the animation 
in a graphics device (either on or off-screen). SpriteLayers are 
an organizational data structure used to group Sprites. Sprites 
are the graphic objects that move about and animate on 
screen. Frames are the individual animation frames contained 
by Sprites, consisting of a pixel map and a mask image. An 
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a[)plicali(>n may contain any number of SpriteWorlcls, a 
SpriteWorld may contain any number of Spritehiyers, a 
SpritcLaycr may contain any number of Sprites, and a Sprite 
may contain any number of Frames. For the remainder of the 
article, the words “SpriteWorld”, “SpriteLayer”, “Sprite” and 
“Frame” will be capitalized when referring to the actual 
SpriteWorld data structures for clarity. 

SpriteWorlds 

SpriteWorlds arc the master data structures used to 
control the animation. A SpriteWorld contains three Frames 
used internally for drawing; a background Frame, a work- 
area Frame, and a window Frame into which the final 
animation image is displayed. A SpriteWorld also contains a 
list of the SpriteLayers that it holds. SpriteWorlds which 
employ a tiled background (a background comprised of 
.several smaller, repeating images which can be animated 
themselves) will contain a tile map data structure. 
SpriteWorlds which employ scrolling animation (animation in 
which the visible area is smaller than the total area of the 
animated world) will maintain additional data structures to 
track the movement of the viewable area of animation with 
respect to the total animated world. 

SpriteWorlds control the erasing and drawing of sprites 
as they move about and iterate through their animation 
frames, updating the data structures of its SpriteLayers and 
their Sprites accordingly. They can do so at regular time 
intervals if the programmer reejuests that a specific animation 
frame rate be used via a call to the function 
SWSetSpriteWorldMaxFPSO, or the SpriteWorld can be left to 
animate as fa.st as the hardware will allow. By default, a 
SpriteWorld uses CopyBits() for all drawing, but a number of 
custom blitters are included with the SpriteWorld {package 
and are easily implemented for increased speed if desired. To 
aid in the creation of SpriteWorlds, there are a number of 
routines available to the programmer; for instance, to creale 
a SpriteWorld from an existing window, 
SWCreateSpriteWorldFromWindowO can be used. 

SpriteLayers 

SpriteLayers are e.ssentially nodes in a linked list u.sed to 
provide a method of sorting Sprites, very similar in concept to 
the layering schemes found in higher-end graphics programs. 
A SpriteWorld will have one or more SpriteLayers, and each 
layer can contain any number of Sprites. The ordering of 
SpriteLayers determines the order in which drawing occurs; 
the bottom layer is drawn first, and the top layer is drawn la.st. 
In addition, Sprites within individual layers are drawn in the 
order which they have been added to that layer. 'Fherefore, a 
Sprite on one layer can be covered by Sprites on higher layers 


as well as Sprites on the .same layer which were added after 
that Sprite, providing a sense of depth. 

As an example, refer to the following illustrations which 
depict a SpriteWorld containing four Sj^riteLayers. A .scene has 
been painted in the SpriteWorld’s background Frame, which 
is drawn first. Then the sprites on each layer are drawn, from 
the bottom layer (containing the car sprite) to the top layer 
(containing one of the character sprites). Note that the same 
visual result could also have been realized by instead using a 
single SpriteLayer with the car sprite added first followed by 
the three character sprites. 



Figure 1, Sprite Layer Conceptual Illustration. 



Figure 2. Animation As Displayed On Screen. 


Finally, SpriteLayers are also the basis for the collision 
detection methods in SpriteWorld. When one wants to check 
for a collision between Sprites in SpriteWorld, the collision 
detection is done against two layers (or one layer against itself 
to check for collisions between Sprites on the .same layer) 
using the SWCollldeSpriteLayerO routine. As an example, one 
could have two SpriteLayers, one for enemy space ships (call 
it enemyLayerPtr) and one for friendly space ships (call it 
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friendlyLayerPtr). To clicck if any enemy spaee ships have 
collided with friendly ships, the code used would be: 

SWCollideSpriteLayer(eiiemyLayerPtr, friendlyLayerPtr); 

'lb take this a step further, one could check to see if any 
friendly ships had collided with each other: 

SWCollideSpriteLayer(friendlyLayerPtr, friendlyLayerPtr); 

If a collision is detected between Sprites, each Sprite 
involved in the collision will have its collision call-back 
routine called (if it has one), which will determine how the 
Sprite reacts to the collision. Tf a Sprite has not had a collision 
call-back routine installed, it will simply pass through other 
Sprites regardless of any collisions which take place. 

Sprites 

Sprites are the workhorses in Sprite World. In addition to 
containing the image information used to display the 
animation graphics on screen in the form of an array of Sprite 
Frames, a Sprite contains data used to define its position in 
the Sprite World, its velocity, tlie frame rate of its animation, 
and other internally used information. Sprites may also 
contain a number of callback routines used to control such 
things as the Sprite’s movement, response to collision, 
behavior when there is to be a change in the currently drawn 
animation frame, and the implementation of custom blitters 
for drawing the Sprite. 

A number of routines are available to the programmer to 
create Sprites from standard Macintosh resource types, namely 
‘PICT and ‘cicn’ resources. These include: 

• SWCreateSpriteFromCicnResourceO which will create a 

Sprite from a series of ‘cicn’ resources to be used as the 
sprite Frames. 

• SWCreateSpriteFromPictResourceO which will create a 

Sprite from a series of ‘PICT’ resources to be used as the 

sprite Frames. 

• SWCreateSpriteFromSinglePictO which will create a Sprite 
from a single ‘PICT’ resource, which contains a number of 
images, either varying in size and location within the ‘PICT 
or of identical size arranged in a horizontal or vertical strip, 
to be used as the sprite Frames. 

• SWCreateSpriteFromSinglePictXYO which will create a 

Sprite from a single ‘PICT’ resource, which contains a 
number of images arranged in rows and columns to be 
used as the sprite Frames. 

On 68k Macintosh systems which will be displaying a 
SpriteWorld animation in 8-bit depth, the programmer has the 
additional option of using compiled Sprites for maximum 


po.ssible speed. Using compiled Sprites causes the Sprite to 
be drawn off screen with binary code generated specifically 
for that Sprite’s pixel map images. 

Frames 

Frames are data structures that store the actual image 
data used in the animation. They consist primarily of a pixel 
image stored in a GWorld and a mask used when drawing the 
pixel image. Think of frames as being similar to the 
individual frames on a reel of film, which when shown in 
rapid succession one after another provide the illusion of a 
smooth display. 

Programming with SpriteWorld 

There are typically six steps to creating and running a 
SpriteWorld program: 

• Initialization of the SpriteWorld package with a call to 
SWEnterSpriteWorld(). 

• Create the components of your animation — SpriteWorld(s), 
SpriteLayers, Sprites and the Sprite Frames. 
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• Assemble llie various components — add the Frames to the 
Sprites, add the Sprites to the a[)propriate SpriteLayers, add 
the Spritebiyers to the appropriate S[)riteWorlds. 

• Assign the desired custom movement, collision, drawing and 
frame advancement procedures to the Sprites in order to 
define their Ix^havior. 

• Run the animation with repeated calls to the 
SWProcessSpriteWorldO and SWAnimateSpriteWorld() 
functions in a tight loop, optionally performing any 
desired collision detection. These two SpriteWorld 
functions will handle all of the drawing and call any 
installed movement, collision and frame advancing 
procedures installed in the S|)rites automatically. 

• When fini.shed, dispose of any SpriteWorld data created for 
the animation. 

Now that a general overview of the SpriteWorld library 
has been presented, a sample program is in order, 'fhe 
following program (which is a trimmed down version of one 
of the SpriteWorld sample programs by Vei n Jensen) creates a 
SpriteWorld from the application’s window, and makes use of 
both the tiling and scrolling features to provide a large 
“virtual” world within which the main Sprite (a blue ball) will 
move abotit. It creates the main Sprite from a sec|uence of 
‘cicn’ resources, and adds a movement routine to the Sprite, 
which allows the Sprite's motion to be controlled via keyboard 
input. A little bit of extra code was added to allow collisions 
between the Sprite and certain tiles (repre.senting walls) to be 
detected. The result is a program that allows the u.ser to 
control the Sprite with the keyboard, moving it about in the 
virtual world and causing it to jump across platforms. Note 
that the initialization of the Macintosh Toolbox is taken care 
of using a special SpriteWorld utility function, lnitialize(). 

Listing I. .SW_I)cm().c 

// SW_l)enu).c 

// indiidc some required SpriteWorld header files 
//include "SWIncludes.h” 

// include a demo-specific header 
//include '’SW_Demo.h” 

// main 

void inain(void) 

I 

Initialize(0); 

AllowKcytlpEvonlu0 : 

CreateSpriteWorld0; 

CreateSpritesO ; 

Set.lJpAn imat ion(): 

Anima t ioriLoop (): 

ShutDownO ; 

RestoreEventMaskO ; 

) 


In the function CreateSpriteWorld(), we perform the first step 
described earlier, initializittion of the SpriteWorld package with a 
call to SWEnterSpriteWorldO, and part of the second step with the 
creation of the SpriteWorld. I’he SpriteWorld created will 
incoqx:)rate lx)th a scrolling display and a tiled background. The 
tile map used for the background in this example is coastructed 
using a iiredetemiined algorithm to provide a boundary of “wall” 
tiles, “step” tiles and “sky” tiles. 


Listing 2. CrcalcSpriieWorldO 

// CreateSpriteWorld 

void CreateSpriteWorld(void) 

{ 

Rect offscreenRect, worldRect, windRect; 

OSErr err; 
short row, col; 

gWindowP = GelNewCWindow(kWlndowResTD, NULL, 

(WindowPtr)-IL); 

ShowWindow(gWindowP); 

SetPort(gWindowP); 

err “ SWEnicrSprireWorld(); 

worldRect = gWindowP->portRecl; 

InsetRect(&woridRect. kWorldRectInset. kWorldReellnsoL); 

// Set size of oftkrreen area 
offscreenRect = worldRect; 

Of fselRcct (6foffscreenRecr , - off.screenRect. left, 
-offscreenRect., Lop) ; 

// (Create ttie strolling sprite world 

err = SWCreateSpriteWorldFromWindow(&gSpriteWoridP. 
(CWindowPtr)gWindowP, ^worldRect, &offscreenRect); 

// Initialize the tiling ft'atnres of SpriteWorld, 

// since tliis program is going to itse them 
err - SWInitTilingCgSpriteWorldP, kTilelleighl, 
kTileWidth, kMaxNumTiles); 

// Oeate the tile map 

err = SWCreateTileMapCgSpriteWorldP, igTileMap, 
kTi1eMapRows, kTileMapCols); 

// l,oad first set of tiles 

err = SWLoadTilesFromPictResource( 
gSpriteWorldP, 
kWallTile, //startTilelD 
kSkyTile. //endTilell) 

700, //pietRe.sII) 

0. // ma.skResII) 

kNoMask. // maskType 

1. // horizBorderWidlh 

1) : // verlBorderl leight 

// Set up the tileMap according to a predetermined 
// .scheme, with the tile map consisting of 
// “sky" tiles and “wall" tiles 

for (row = 0: row < kTileMupRows: row-H-) 

I 

for (col - 0; col < kTileMapCols; col-H-) 

I 

if (row <= A II col <= 3 JI 
row >= kTi 1 eMapRows-*) || 
col >= kTileMapCols A) 

1 

gTiieMapIrowj IcolJ = kWallTile; 

1 

else 

I 

gTiieMap[row][col] = kSkyTile; 

1 

I 

I 
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// Draw the platforms 

for (row ^ kTileMapRows-7, col = 6: row > 5 && 
col < kTllcMiipCols*8; row--, col 1= 4) 

I 

gTileMaplrow][col] = kWallTile; 
gTileMap(rowj Lcol+lJ = kWallTile; 

1 

I 


In the function CreateSprites(), we finish the second siep 
wiili the creation of the Sprites (and at the same time their 
Frames), and then move on to the third step by adding the 
Sprites to the SpriteLayer, and the SpriteLayer to the 
SpriteWorld. The Sf)rileWorld is also “locked” with a call to 
SWLockSpriteWorld(). Loc king a S[)riieWorid is necessary before 
animation begins, as it locks the many Handles used to keep 
their memory from moving during animation. 


listing 3. CreateSpritcsO 

// CreateSpritcs 

void CroateSprites(void) 

( 

SpriteLayerPlr spr i tel.ayerP; 

OSErr err; 

// (Create the sprite layer 

err = SWCreateSpriteLayer(&spriteLayerP): 

FatalError(err); 

// Create the main sprite from 'cicn' resources 

err = SWCrealeSpri icFromCicnRer.onrr.e(gSpriteWorldP, 
&gSinipleSpriteP, NULL. 129, 1. kRcgionMask) ; 

FatalError(err); 

// Set up the main sprite 

SWSclSprireMoveProc(gSimpleSpriteP, KeySpriteMoveProc): 
SWSelSpr 1 icl.oear ion (gSimpleSpriteP, 
kStartCol * kTilcWldth, 
kStartRow * kTilelleighl) : 

SWSetSpriteMoveDelta(gSimpleSpriteP. 0. 0); 

// Add the sprite to the sprite layer 
SWAddSprite(spriteLayerP, gSimpleSpriteP); 

// Add the .sprite layer to the .sprite world 
SWAddSprileLaycr(gSpritoWorldP. spriteLayerP); 

// Lx:k the sprite workl 
SWLockSpriteWorld(gSpriteWorldP): 


The function SetUpAnimation() is used to perform the fourlli 
step in creating our animation, which is the assignment of the 
special f)rocedures to the Sprite(s) which will determine their 
behavior, and setting up some additional parameters for the 
SpriteWorld such as maximum animation speed and a special 
prcK’edure to control the scrolling movement of the display 
during animation. Once the animation is set up, we draw the tiles 
in the background of the SpriteWorld and force the screen 
display to update with calls to SWDrawTileslnBackground() and 
SWUpdateScrollingSpriteWorldO respectively. 
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listing 4 . SciUpAniniationO 


Listing 6. ShutDownO 


// SctUpAnimation 

void SetUpAnimation(void) 

I 

Rect moveBoundsRect: 

// Place an upper limit on the animation speed 

SWSetSpriteWorldMaxFPS(gSprltcWorldP. kMaxfPS); 

// Set the sprite’s movement boundary 

// movement lx)undary = size of lilcMap 

SetRect(&moveBoundsRect, 0,0, kTileMapCols * kTileWidth, 
kTileMapRows * kTileHeight); 

SWSetScroningWorldMoveRounds(gSpriteWorldP. 
{fmovcBoundsRccL) ; 

SWSetScrollingWorldMoveProc(gSpriteWorldP, 

SmoothScrollingWoridMoveProc, gSimpleSpriteP): 

// Move the visible scrolling view to starting 

// sprite position 

SWMoveVisScrollRect(gSpriteWorldP, 

gSpriteWorldP >followSpriteP >dGstFranieRect.left - 
gSpriteWorldP->backRect.right/2. 
gSpriteWorldP->followSpriteP->destFrameRect.top - 
gSpriteWorldP* >backRect.bottom/2); 

ForeColor(blackColor): 

BaekColor(whiteColor); 

SWDrawTileslriBackground(gSpriteWorldP) ; 

SWUpdateScrollingSpriteWorld(gSpriteWorldP, true); 


With the function AnimationLoopO the fifth step in our 
SpriteWoiicl animation is achieved, which is to drive the 
animation in a tight loop. The animation in this example has 
been setup so as to run until the mouse button is clicked. 


Listing 5. AnimationLoopO 

// AnimationLoop 

void AnimationLoop(void) 

I 

//'llie animation will run until the mouse Is clicked 
while (IButtonO) 

( 

SWProcessScrollingSpriteWorld(gSpriteWorldP); 
SWAnimateSerollingSpriteWorld(gSpriteWorldP); 

1 


The last step in a SprileWorld program is to dispose of 
the objects we have created and ask the SpriteWoiid engine 
to clean up after itself. This is done within the ShutDown() 
routine of our sample program, which unlocks the 
SpriteWorld with a call to SWUnlockSpriteWorld() (matching 
the earlier call to SWLockSpriteWorld()), frees all memory used 
with a call to SWDisposeSprlteWorId() and finishes cleaning up 
with a call to SWExltSpriteWorld() (matching the earlier call to 
SWEnterSpriteWorldO). 


// ShutDown (clean up and dispose of the SpriteWorid) 
void ShutDown(void) 

I 

SWUnlockSpriteWorld(gSpriteWorldP): 
SWUlsposeSpriteWorId(gSpriteWorldP): 
SWExitSpriteWorldO ; 

FlushEvents(GveryEvent. 0); 

1 



Figure J. Demo Program Screen. 


Conclusion 

Using SpriteWorld, the developer is able to build 
applications using sprite animation quickly and easily without 
needing to worry about the low level implementation of the 
animation engine itself. Animation can be a simple “set up and 
forget” endeavor, or they can be cjuite complex, with several 
sprites who.se behavior changes dynamically. The excellent 
documentation and abundant sample code make it easy for 
the beginner to get started with SpriteWorld, while the 
availability of the source code lets the more advanced user dig 
into the API and expand upon it if need be. 

To download the SpriteWorld [)ackage, you can visit the 
SpriteWorld web page at <http://niembers.aol.com/SpriteWld2/> or 
the corresponding SprileWorld FTP site at 
<ftp://members.aol.com/SpriteWld2/>. SpriteWorld is also available 
from any of the Info-Mac mirrors. There is also a SpriteWorld 
mailing list; instructions for subscribing to the SpriteWorld 
mailing list can be obtained on the Web at 
<http://www.us.itd.umich.edu/~hinoue/mailinglist.html>. 
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somewhere so obscure that no 
sane person would consider looking there? 
Have an unanswered programming question 
so important that you tliink the world would 
want to know the answer as well? 

Need some beer money? 

Want your friends to see your 
name in print? 

Tell us about it! Write it up and send it to 
<tips@mactech.com>. We pay $25 for each tip 
published, and $50 for the Tip of the Month. 


StoneTable 

You thought it was just a replacement 
for the List Manager ? 

We lied, it is much more ! 

Tired of always adding just one more feature to your LDEF or 
table code ? What do you need in your table ? 

Pictures and Icons and Checkboxes ? 
adjustable columns or rows ? 

Titles for columns or rows ? 

In-line editing of cell text ? 

More than 32K of data ? 

Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make it worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today ! 

Only $200.00 MasterCard & Visa accepted. 

StoneTablet Publishing 
More Info & demo Voice/FAX (503) 287-3424 

http://www.teleport.com/--stack stack@teleport.com 


Help Make Ma(Tech Work 


Hei-e at MacTech Magazine, we rely heavily on 
outside winters for most of the material tkit 
apjnears in oui’ pages. If readei-s did not 
participate in the maga:?:ine, sending us their 
ideas and taking the time to write articles, there 
would be no MacTech. MacTech Magazine is 
not a staff of writers sending a constant stream 
of one-way messages outwards; it’s a living, 
evolving network of readers conversing with 
one another, educ*ating one another, sharing 
iheir knowledge, iheir experience, tlieir interest, 
their trials and tribulations and joys and 
successes in the constantly unfolding story of 
programming tlie Macintosli. MacTech 
Magazine doesn’t just happen: it’s what the 
community makes it. If we carry reports of 
future trends and technologies, if we teach 


useful methods, if we review new books and 
tools, if we provoke thought, provide help, ride 
tlie wave of current interests and concerns, it is 
only because we reflect the thoughts of our 
readers, who speak tlirough our pages. 

You are invited to involve yourself in 
this exciting conversation amongst readers. 
No matter who you are, no matter what your 
credentials may be, if you have a tale to tell, 
a trick to share, a technique to teach, we 
want you to consider joining the family of 
those who write for MacTech. 

Don’t just wait- for a topic to be covered 
or a technique explained in MacTech! Take 
responsibility! Write us an article yourself! 

lb write for MacTech, just send for our 
Writer’s Kit. It’s a Microsoft Word file 


containing the Styles you need to use, and 
giving lots of helpful advice and information, 
including all the legal stuff. You can let us 
know what you’re writing about, or, if you 
want to, you can just write the article and 
spring it on us when it’s done. [Note: We 
also have a need for people willing to make 
themselves available to write occasional 
product/book reviews.l If we publish your 
article, you’ll be paid for it! 

Write to us, the editorial staff, at 
editorial@mactech.com (or one of the other 
addresses listed on page 2 of the magazine), 
lake the future of MacTech Magazine into 
your own hands! 


forUacluMtb 

Programmert & Ottulofttn 



MAGAZINE 


July 1998 • MacTech 


59 






















Y)u’ll be stuck in the 
heaviest traffic in New Wk City 
and loving every minute of it. 


This year at Macworld, Apple is going to make it easier for all developers, big and small, 
to get a space as special as their ideas. Apple Computer and Maclech'^ Magazine 
introduce “Developer Centralan exhibit at Macworld that showcases development for 
the Macintosh in the biggest possible way. Macworld will be held in New York City, 
July 8-10,1998. Check out the Exhibitor Information for the product exposition at: 



Think different? 



© IS9S Apple Computer. Inc Ml reserved and the ^\pplc logo are ngistcrcd trademarks. Think different and Deivloper 

(antral are trademarks Apf^e Computer, Inc. MacTecb Magazine is a registered trademark of Xplain Corporation 





FROM THE 

FACTORY 

FLOOR 


by Andreas Hommel, Howard Hinnant, and Dave Mark, ©1998 by Metrowerks, Inc., all rights reserved. 


The New C++ Standard: Namespaces 


By the time you read this, the Final 
Draft International Standard for C++ should 
be finalized, approved, and made available 
for purchase (see last month’s inteiYiew 
with Ron Liechty for specifics on where to 
go to get your copy). In this month’s 
column, our old friend Andreas Hommel, 
along with new friend Howard Hinnant 
will tackle an important part of the new 
standard: C++ namespaces. 

Andreas Hoinmel is currently the 
C/C++ front-end and 68K back-end 
architect at Metrowerks. After finishing 
his Master’s degree in Computer 
Science, Andreas did some contract 
programming in the desktop publishing 
area and also published several games 
on the Macintosh and Amiga. He has 
been with Metrowerks for five years. 

Andreas lives in a small country 
village about 20 kilometers north of 
Hamburg, with his wife, two Australian 
Shepherd dogs, two Arabian horses and 
one Quarter horse. When he is not 
coding, riding horses or walking his 
dogs, Andreas likes running, traveling, 
playing a good video game, and driving 
really fast on the Autobahn. He also 
likes cooking and fine red wines 
(California cabernets, in particular). 

Howard Hinnant is a software 
engineer on the MSL team at Metiowerks, 
and is responsible for the C++ and EC++ 
libraries. Howard is a refiigee from the 
aerospace industry where FORTRAN still 
rules. He has extensive experience in 
scientific computing including C++ im¬ 
plementations of linear algebra, finite 
difference and finite element solvers. 


Dave: What are C++ namespaces? 

Andreas: Namespaces are one of the newer ANSI C++ features. 
Iftey allow a programmer to define new named or unnamed 
declarative regions. The original C++ (and ANSI C) only had 
one global namespace, but now it is possible to have many 
user defined namespaces. 


For example: 

name!5pace metro { 
int foo(); 

Int bar; 


defines a namespace ‘metro’ and declares the namespace 
member function Too’ and defines a namespace member 
variable ‘bar’. You can define anything inside a namespace 
that can be defined in the global C++ namespace, even other 
nested namespaces. All these namespace members can then 
be used using qualified-ids. 

For example: 

int i = metro:;foo() t metro::bar; 

would call metro’s member ‘foo()’. So this is veiy similar to a 
C++ class definition. In fact we could have created something 
very similar using static class members: 

cla.q.s metro_cla.'ss ( 
public: 

static int foo(); 
static int bar; 

); 

int j = metro_c.Iass: :foo() + metro_class: :bar; 

However, there are difterences between a class and a namespace. 
You cannot create any instances of a namespace (ie a namespace 
variable or a fxiintcr to a namespace) and all data and function 
namespace memloers behave like static class members (non-static 
namespace members wouldn’t make any .sense when you cannot 
have a namespace instance). So namespaces have more 
restiictions tlian classes. However, they have the advantage that 
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you can split the dehnition of a namespace over several parts of 
one or more translation units (ie souixr and header files). So you 
can add new definitions later on. 

For example 

namespace metro I 
int baz(); 

) 

adds the function ‘baz’ to our ‘metro’ namespace and this 
could be done in the same or any other source or header file. 

Dave: So you have to use qualified-ids to access 

namespace members. Are there any mechanisms in C++ 
to simplify this? 

Andreas: Yes, First, you don’t have to use (|ualified-ids if you 
are accessing namespace memters witliin the same or nested 
namespace. So you can do something like this: 

namespace metro ( 

int k " bar; //no qualification ncccssar>', uses mctix)::bar 

1 

or even: 

int metro:: baz () // define metro::ba 2 outside of namespace 
( 

return f oo (); // no qualification necessary, uses metro::foo 

) 

But, there are also language extensions that simplify the use of 
namespace meml:)ers outside of the namespace. One is a ‘using- 
declaration’ that c*an lx.* useful if you are using a particular 
namespace memter over and over again. For example: 

using metro: :bar: //using declaration 

int m " bar; //no qualification necessary, uses metn):: bar 

introduces metro’s member bar to the current namespace 
which enables you to use metro::bar without any qualification. 

'Ihe other major extension is called a ‘using-directive’ which 
will introduce all names defined in a namespace. For example: 

using namespace metro; //asing-directive 
int n = foot) + baz(); //no qualification necessary,ases 
// metro: :foo and metro; :ba7. 

Dave: Wliat is an unnamed namespace? 

Andreas: An unnamed namespace like: 
namespace ( int o; } 

Ixjhaves as if was replaced by: 

namespace <unique> I ) 
using namespace <unique>: 
namespace <unique> { int o; ) 


where <unique> is replaced with a translation unit specific 
identifier that is different from all other identifiers in a 
program. So it will be possible to access ‘o’ without any 
qualifications in the same translation unit: 

void f() ( 0 ++; ) //U.SCS <uniquc>::o 

but, not from any other translation unit. So this is very similar to: 

.static int o; 
void f() I 0++; ) 

Ihe use of the ‘static’ keyword in namespace scope is actually 
deprecated in the current C++ draft. 

Dave: Why would you want to use namespaces? 

Andreas: Namespaces are very useful for libraries because they 
can used to avoid name collisions. Tf you have a program 
that has a function ‘fex)’ and you want to use a third party library 
that has a different function with the same name you would 
have to change your on program or the library to be able to use 
this library. If this li[)rary would liave used its own namespace 
(e.g., ‘metro’ from the example above) you wouldn’t have this 
problem. A good example for this is the std:: namespace tliat is 
used to implement the standard C++ library. 

Dave: What did it take to get the libraries under 

namespace std? 

Howard: Putting MSL (Metrowerks Standard Libraries) under 
namespace .std t(K)k a lot more work than we had originally 
envisioned. Tliere were many issues which needed sorting out, 
prioritizing, and dealing with within the lime allowed. Witliout 
the aid of the entire MSL Tc‘ain (hciided by Vicki Scott) we 
would never have pulled it off so quickly. But it was more than 
just team work within the MSL Team that counted. Tight and 
rapid response lx‘tween tlie MSL Team and the Compiler learn 
was CRicial. Tliere were many very subtle effects and 
interactions between the compiler’s implementation of 
namespaces, and die libraiy’s use of namespaces. Andreas is 
great at getting to the heart of a problem, and providing a 
solution in an amazingly short amounl of time. 

Dave: What effect will namespaces have on legacy code? 

Howard: Standard namespaces have quite a bit of backward 
compatibility built into them to ease the porting of 
namespace-ignorant cxxle. We liave implemented all of this 
compatibility, and where we thought was important, added 
even more backward compatibility. 
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Standard header names have become very particular, and veiy 
important. In previous releases, <iostream> and <iostream.h> 
were interchangeable. So were <cstdio> and <stdio.h>. I'his is 
no longer the case. As a general rule of thumb, namespace- 
ignorant code should use headers that end with the .h 
extension. If you use the extension-less headers, then your code 
should be “namespace std aware”. 

For example, the following HelloWorld will compile and 
run correctly: 

//include <iostream.h> 

int mainO 
{ 

coul << “Hi\ri": 

) 

But this will fail with a compiler error: 

//include <iostream> 

int mainO 
I 

cout << “Hi\n”; 

) 

You can make the above HelloWorld work in one of two 
ways: You can provide a using declaration: 

//include <iostrGam> 

int mainO 
f 

using namespace std; 
cout << “Hi\n”; 

1 

Or you can provide the full name of objects in the 
standard library: 

//include <iostream> 

int mainO 
{ 

std::cout << “Hi\n”; 

) 

The purpose of namespace std is to keep library names 
from conflicting with your own. With a name like cout, a 
conflict doesn't seem likely. But, consider the name vector 
or stack. Many users might want to use such names. Such 
users may even be unaware of their existence in the 
libraiy. Now that these names are under a namespace, 
such conflicts are less likely. 

Dave: Does namespace affect the C library? 



ITRATTNER NETWORK 
The Trattner Network, 

"The Digital Talent Source", 

is looking for experienced Macintosh developers for cutting edge 
opportunities in Northern California and Nationwide. 

TTN is plugged into projects in UI, Internet, Multimedia, 

Cross platform, and "The newest and hottest developments"! 

Visit our web site at: www.tratnet.com and see what 
openings are available for: 

JAVA/Internet Stars ■ Software Developers 
QA/QC Professionals ■ Project Coordinator/Manager 
Multimedia Developers ■ Network Professionals 

The Trattner Network has a unique history in Mac consulting coupled 
with exposure to emerging technologies. If you are looking for a chance 
to enhance your skills and marketability, please email or fax resume to: 

The Trattner Network ■ Attn: Debbie Stevens 
170 State St., Suite 240 ■ Los Altos, CA 94022 
Phone (415) 949-9555 ext. 115 ■ Fax (415) 949-1026 
email: dstevens@tratnet.com 


Howard: The “C” library is also under namespace std when 
used from a C+-i- program. That is, printPs new name is 
std::printf. Remember, this is only when using the C++ 
compiler. C programs will continue to use just plain printf. 
Also note that if a C++ program includes <stdio.h> instead of 
<cstdio>, then printf is promoted to the global namespace. So 
again, just plain printf can be used, 

KSfii 


Want to subscribe to MacTech 
Magazine? Contact 
<mailto:orders@devdepot.com>, 
call 800/MACDEV-l, 
805/494-9797, or 
fax us at 805/494-9798 
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PROGRAIVIMER'S 

CHALLENGE 


by Bob Boonstra, Westford, MA 



Going Up? 


Your Elevator routine will be called with the number of 


Welcome to the Programmer’s Challenge Skyscraper. Your 
Challenge this month is to assume control of our skyscraper’s 
elevators and efficiently move a dedicated crew of simulated 
employees up and down the building. 

Yhe prototype for the cxxle you should write is: 

//if defined(_cplusplus) 

extern "C" ( 

Ifondif 

//define kMaxFloors 500 
//define kMaxElevators 100 
//define kElevatorCapacity 16 


typedef enum { 
kGoingUp=l, 
kGoingDown, 
kSloppcdGoingUp, 
kStoppedGoingDown. 
kStoppedIdle 
} CarAction: 


r commanded action for elevator car 7 
r send car up one floor 7 
/• send car do>vn one floor 7 
/* stop car at an intermcdiaic fltwr, car going up */ 

/* stop car at an intermediate lloor, car going down 7 
r stop car, car in idle state 7 


typedef struct CarState 1 

1 ong at Floor: /* current location of car 7 

long goingToFloor[kMaxFloorsl ; 

/* goingToFloorli] is the number of passengers in the car is going to floor li] 7 
) CarState; 

typedef Boolean (‘AdvanceTimeProc) ( 

r rctuni value ofTRUE nu“aiis Elevator should exit 7 
Ca r Act ion action [kMaxElevators j, /* direction you move each elevator 7 

CarState newState [kMaxElevators]. /* returns ik*w state of each elevator 7 
Boolean stopsAtFloor[kMaxFloors]. 

r stopsAtFloor(il=TRUE means elevator stops at fl(M)r i 7 
Boolean callGoingUp[kMaxFloors]. 

r call(ioingUplil== rRUE means a passenger on fl(H)r i wants to go up 7 
Boolean callGoingDown[kMaxFioorsj 

/* callGoingDown(i]==TRUE means a passenger on fl(K)r i wjints to go down 7 


void Elevator( 

long numFloors, /* number of floors in our building, < kMaxFloors 7 

long numElevators. /* number of elevators in our building, < kMaxElevators 7 
AdvanceTimeProc AdvanceTime /* callback to get new state 7 

); 

//if defined(_ cplusplus) 

I 

//endif 


floors (numFloors) in our simulated skyscraper, the number of 
elevators (numElevators) at your command, and a callback 
routine (AdvanceTime). You should repeatedly call AdvanceTime, 
commanding an action and a set of constraints (stopsAtFloor) for 
each elevator car and receiving back the newState of each car. 
AdvanceTime will also provide an indicator of whether any 
prospective passengers on floor I have called an elevator to take 
them higher (callGoingUpfi]) or lower (callGoingDown[i]). 

The newState returned by AdvanceTime provides the Icxration 
of each car and the number of occupants. atFloor is the floor at 
which the car is now located. Our elevator passengers are 
extraordinarily cooperative — on entering, they all indicate their 
destination by pressing the button corresponding to their floor, 
whether or not that floor has already been selected, allowing 
AdvanceTime to give you an accurate count of the passengers 
going to floor i (golngToFloor[l]). Our passengers are also 
extraordinarily swift — they exit and enter in such an orderly 
fashion that the passenger exchange takes place in one time step. 

Each call to AdvanceTime will move all the elevators one 
floor in the direction you indicate. If you stop the car by setting 
action to kStoppedGoIngUp, kStoppedGoingDown, or kStoppedIdle, 
passengers headed for the current floor will exit and new 
pas.sengers, up to kElevatorCapacity, will enter. Almost always, 
passengers headed to higher (or lower) fl(x)rs will only enter 
elevators that are kStoppedGoingUp (kStoppedGoingDown) or 
kStoppedIdle, but occasionally someone will be confused and 
enter an elevator headed in the wrong direction. 

You are free to nin your elevators anyway you see fit, except 
that a car declared to lx: kGoingUp (or kGoingDown) needs to 
continue going up (or down) until all passengers headed in tliat 
direction have exited. You can designate elevators to \yc express 
elevators by setting stopsAtFloor[i] to l^e FALSE for floors where this 
elevator does not stop. Passengers wiU only enter cars that will 
stop at their intended destination. You can change the stopsAtFloor 


THE RULES 


Here’s how ii works: each month we present a new programming 
challenge. First, write .some code that solves the challenge. Second, optimize 
your code (a lot). Then, submit your solution to MacTech Magazine. We 
choose a winner based on code correctne.ss, speed, size, and elegance (in 
that order of importance) as well as the subrnKssion date. In the event of 
multiple equally desirable solutions, we’ll choose one winner (with 
honorable mention, but no prize, given to the runner up). The prize for each 
month’s best solution is a $100 credit for Developer Depot^. 

Unless stated othcrwi.se in the problem .statement, tlie following rules apply: 
All solutions must l^e in ANSI cx)mpatiblc C or C++, or in Pa.scal. We disqualify 
entries witli any assembly in tliem (except for challenges .specifically .stating 
otlierwlse.) You may call any Macintosh Toolbox routine (c.g., it doesn’t matter if 
you u.se NewPtr instead of mallcK*). We compile all entries into native PowerPC 
code with compiler optioas set to enable all available speed optimizations. The 
development environment to be used for .selecting the winner will lx? .slated in the 
problem, liiiiit your code to 60 characters per line or compre.ss and binliex ilie 


.solution; tills helps witli e-mail gateways and page layout. 

We publish the solution and winners for each month’s Programmer’s 
Challenge three months later. All submissions must be received by the l.st day 
of the month printed on the front cover of this issue. 

You can get a head .start on the Challenge by reading the Programmer’s 
Challenge mailing list. It will be posted to the li.st on or before tlie 12lh of the 
preceding montli. To join, send an email to listscrv@li.stmail.xplain.com with 
the .subject “.subscribe challenge-A”. 

Mark .solutions “Attn: Programmer’s Challenge Solution” and send it by 
e-mail to one of the Progmmmer’s Challenge addre.sses in the “How to 
Communicate With Us” section on page 2 of this i.ssue. Include the solution, 
all related files, and your contact info. 

MacTech Magazine reserves the right to publish any .solution entered in 
the Programmer’s Challenge. Authors grant MacTech Magazine the exclusive 
right to publish entries without limitation upon submission of each entry. 
Authors retain copyrights for the code. 
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I Sland-^lone version control lool.wilh eaiy-tOHJse graphical user into 
il Smooth integratron with MetrowertcsCodeWarrior. BBEdit and other applications 
I Simple and dear managerneril ol variartts and revisions of entire projects (not only single files) 
I Suitable for all sorts of projects {software developrnent, web publishing, design^ CAD, etc.) 
Mecording of the complete project history (who made which changes when andwhy) 
il View differences between versions of files (for different file types • not only for text files!) 

$ Effidenl delta storage (95 % savings and more) for files of arbitrary type 
jj Administration of users with hierarchical access rights 
i5 Configurable local file locking (finder flag or'ckid'resource) 

I Scnptable via OSA (AppleScript and Frontier) 


n.s.'ii 


^ Easy definition of the project structure by just adding local foWets 
Japanese version available 

^ Open interface for compare helper applkalions ' 

^ Support for MS Word :98 
^ Significant performance improvements in many places 


UNI SOFTWARE PLUS 
A-4232 Hagenberg Austria 

email: voodoo@unisoft.co.at — http://www.unisoft.co.at/products/voodoo.html 


values at any time, l)uL you need to be careful not to strand 
passengers — you can command the car to slop at any time, but 
the door will only open at floor i if stopsAtFloor[i] is TRUE. 

The objective of this Challenge is to deliver passengers to their 
destinations as expeditiously as |:)ossiblc. You incur a co.st of one 
point for each passenger for each time step from die time s/he 
presses the call button until the time s/he exits the elevator. You also 
incur one point for each 10 milliseconds of execution time, including 
the time spent by AdvanceTime. Stranding a passenger inside an 
elevator or not responding to an elevator call button results in 
disqualification of your solution. The .solution that incurs the fewest 
points wias the Challenge. There are no storage constraints for this 
Challenge, except that it must execute on my 96MB 8500/200. 

The Challenge will simulate a normal workday in our 
simulated skyscraper. People arrive at the beginning of the day 
either by entering the parking garage at floor 0 or by walking 
into the main entrance at floor 1. They work in approximately 
equal numbers on floors 2 through numFloors-1. During the day, 
they move about the building as necessary. Somewhere in the 
middle of the day, mexst of them take a lunch break, either at the 
cafeteria on floor 2 or by leaving the building. Nearly everyone 
leaves the building at the end of the day. However, as advanced 
as our elevators are, they don’t have a clock, so you’ll have to 
establish your strategy without knowing the time of day. 

This will be a native PowerPC Challenge, using the latest 
Code Warrior environment. Solutions may be coded in C, C++, or 
Pascal. Ernst Munter wins two Challenge points for suggesting 
this problem, way back in November, 1996. 

Three Months Ago Winner 

Congratulations to Sebastian Maurer for submitting the 
winning entiy to the April Mancala Challenge. Sebastian won a 
round-robin tournament whose object was to efficiently capture 
the most stones in a variant of the ancient game of Mancala. In 
our variant of the game, the number of bowls ranged from 8 to 
32, instead of the traditional 14, and players were allowed to 
move in either the clockwise or counter-clockwise directions. 
Congratulations also to JG Heithcock, who.se solution actually 
captured more stones than Sebastian’s did, but used better than 
50% more execution time to do so. Both of the top solutions used 
an alpha-beta ininmax technicjue to identify the best move, but 
Sebastian’s heuristic for pruning the tree, combined with the time 
penalty of one stone per 100ms of execution time, gave him the 
higher overall score. Seba.stian gained a little extra efficiency by 
partitioning his code into two [)arallcl versions, one for playing 
first and another for playing second. 

Twelve people submitted Mancala solutions, and eleven of 
those solutions |:)aitici[)aLed in the tournament. (One solution 
occasionally made illegal moves, so it was eliminated to avoid 
unevenly affecting the scores of the other players.) The touniament 
consisted of seven test ca.ses, with bcxird sizes of 8,12,16, 20, 24, 28, 
and 32 lx)wls. Each solution played against each other .solution twice 
in each test case, once playing first, and once playing second. The 
top solutions all used some variant of the minmax algorithm, wliile 
the lower ranking solutions u.sed simpler heuri.stics, like always 
favoring moves that dropped the last stone into their mancala. 


The table below lists the results of the tournament, with the 
solutions ranked in order of total points earned. It lists total 
execution time for the tournament, the total number of stones 
captured, the solution rank if execution time had been ignored, 
total points earned, as well as code size, data size, and 
programming language used. As usual, the number in parentheses 
after the entrant’s name is the total number of Challenge points 
earned in all Challenges to date prior to this one. 


Name 

Time 

Cum 

Rank 

Cum 

Code 

Data 

Lang 


(secs) 

Stones (stones) 

1 Points 

Size 

Size 


Sebastian Maurer (10) 54.16 

14764 

2 

14222.40 

3488 

136 

C 

JG Heithcock 

85.37 

14897 

1 

14043.26 

1784 

48 

C++ 

Ken Kaigler 

97.'I5 

14627 

3 

13652.46 

4288 

308 

C++ 

Randy Boring (7.5) 

59.90 

14055 

4 

13456.02 

8048 

824 

c 

Eric Kenninga 

21.10 

13399 

5 

13187.99 

14584 

894 

C++ 

Willeke Rieken (47) 

3.63 

11667 

6 

11630.74 

4088 

8 

C++ 

Simon Jcn.scn-Fcllows 0.33 

11512 

7 

11508.68 

3364 

6147 

C, Res 

Dennis Jones (10) 

2.76 

10383 

9 

10.355.41 

2556 

125 

C++ 

Eric Hangstefer (9) 

0.05 

10252 

10 

10251.54 

3724 

124 

c 

Ernst Munter (362) 

m.% 

11178 

8 

10130.42 

7916 

13 

C++ 

Josh Cooley 

0.27 

9446 

11 

9443.29 

2228 

64 

c 

K. IL 

0.00 

Errors 

12 

().(K) 

.3772 

104 

C++ 
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Top Contestants 

Here are the Top Contestants for the Programmer’s 
Challenge, including everyone who has accumulated more than 
10 points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month’s entrants. 


long *boardStorage, 
const long boardSize, 
long *chosenBowl. 
long 'chosenDirection. 
long lowerBound, 
long upperBound 


// DmpStones — play the move 
// Return true if we get to play again 


Rank 

Name 

Points 

Rank 

Name 

Points 

1. 

Munter, Ernst 

210 

9. 

Gregg, Xan 

24 

2. 

Boring, Randy 

70 

10. 

Murphy, ACC 

24 

3. 

Cooper, Greg 

61 

11. 

Hart, Alan 

21 

4. 

Mallett, Jeff 

50 

12. 

Antoniewicz, Andy 

20 

5. 

Riekcn, Willcke 

47 

13. 

Day, Mark 

20 

6. 

Nicolle, Ludovic 

34 

14. 

Higgins, Charles 

20 

7. 

Lewis, Peter 

31 

15. 

Hosteller, Mai 

20 

8. 

Maurer, Sebastian 

30 

16. 

Studer, Thomas 

20 


There are three ways to earn points: (1) scoring in the top 5 
of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) being tlie first person to 
suggest a Challenge that I use. The points you can win are: 


Boolean DropStonesl( 
long board[]. 
const long boardSize, 
long bowlPlayed, 
long directionPlayed 


Boolean DropStones2( 
long board[], 
const long boardSize. 
long bowlPlayed, 
long directionPlayed 

); 

// SideEmpty return.s true if the side is empty 

// (and the game is over) 

Boolean FirstSideEmpty( 
long board[], 
const long halfBoardSize 


1st place.20 points 

2nd place.10 points 

3rd place.7 points 

4th place.4 points 


5th place.2 points 

finding bug.2 points 

suggesting Challenge...2 points 


Here is Sebastian’s winning solution to the Mancala Challenge: 


MancalaX 


Boolean SecondSideEmpty( 
long board[]. 
const long boardSize 

); 

// Moves all the remaining stones 

// to the appropriate Mancala 

void RemainirigToMancala ( 
long board []. 
const long boardSize, 
const Boolean playerOne 

): 


Copyright 1998, Sebastian M. Maurer 

//include <stdio.h> 

//include “Mancala.h** 

enum I kDefault, kPlayAgain, kGameOver 1: 
typedef long StateOfGame; 

//rhere arc I wo versions of almost ever)' routine 
// so we don't have to decide at run time 
// which side to play on. It speeds things up a 
// little bit 

//AlphaRetal and AlphaBeta2 are the recursive searchers 
// for each of the two players. They return the value of 
// best move (returned in ‘chosenBowI, *choscnDirection). 
// For a description of Minimax and Alphabeta .searches, 

// see Peter Norvig’s 

//“Paradigms of Artificial Intelligence Programming" 
//define kMaxSignedLong 0x7FFFFFFF 


long AlphaBetal( 
long depth, 
long board IJ. 
long ‘boardStorage, 
const long boardSize. 
long *chosenBowl, 
long •chosenDirection. 
long lowerBound, 

r any big negative number to enter recursion 7 
long upperBound 

r any big positive number to enter recursion 7 

); 

long AlphaBeta2( 
long depth, 
long board(] , 


// DoMovc Drops the stones, checks if the game 
// is over (if so, cleans up the board), and 
// returns kGameOver, ld*layAgain, or kDefault 
StateOfGame DoMoveK 
long board[], 
const long boardSize, 
long bowlPlayed, 
long directionPlayed 

): 

StateOfGame DoMove2( 
long board[], 
const long boardSize. 
long bowlPlayed, 
long directionPlayed 

): 

// Called only once from 
// within Mancala 
Boolean ClaimingVictory( 
long board [] , 

PiX)totyix*s const long boardSize, 

const Boolean playerOne 

); 


Mancala 


Boolean Mancala ( /* retuni true if chiming victory 7 

1 ong board [1 /* on entry, boardfil is number of stones in bowl i 7 

r on exit, board reflects the results of your move 7 
const long board S i ze. /* number of bowls in the board, including mancalas 7 
void * privStorage. /* pointer to 1 MB of storage for your use 7 

const Boolean newCame, /* tnie for your first move of a game 7 
const Boolean playerOne. /* true when you are the first player 7 
long * bowlPlayed, /* return the number of the bowl you played finom 7 

long * directionPlayed /* return 1 if you played counter-clockwise, 7 

r return -1 if you played clockwise 7 


) 
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{ 

//pragma unused (newGame) 

// Q&D way to decide how far to search 
// so that we don’t lose too much time 
long depth; 
switch (boardSize) 

{ 


case 

8: 

depth “ 10; 

break; 

case 

10 

depth 

= 8: 

break: 

case 

12 




case 

lA 

depth 

= 6; 

break: 

case 

16 




case 

18 

depth 

= 5; 

break: 

case 

20 




case 

22 




case 

24 




case 

26 

depth 

= 4: 

break; 

case 

28 




case 

30 




case 

32 

depth 

= 3; 

break; 

default 

depth 

= 1; 

break; 


I 

// Start recursion and play move 
if (playerOne) { 

AlphaBetal(depth, board, (long*)privStorage, 
boardSize, bowlPlayed. dircciionPlayed. 
kMaxSignedLong, kMaxSignedLong); 

DropStonesKboard, boardSize, 

•bowiPiayed. *directionPlayed); 

1 

else 

( 

A1phaBeta2(depth, board, {long*)privSLorage. 
boardSize, bowlPlayed, directioriPlayed, 
-kMaxSignedLong, kMaxSignedLong): 

DropStones2(board. boardSize, 

•bowlPlayed, *directionPlayed); 

) 

// Correct to proper convention 

•directionPlayed = - (*directionPlayed); 

return ClaimingVictory(board, boardSize, playerOne): 


AlphaBetal 

long AlphaBetal( 
long depth, 
long board [], 
long *boardStorage, 
const long boardSize, 
long ‘chosenBowl. 
long *chosenDirection, 
long lowerBound, 
long iipperBoimd 

) 

( 

long rayMancala, hisMancala, firstBowl, halfBoardSize: 
long bowl, dir, value, bestBowi, bestDir: 
long 'workingBoard: 

halfBoardSize = boardSize / 2; 

workIngBoard = boardStorage + depth * boardSize; 

myMancala = 0; 

hisMancala = halfBoardSize; 

firstBowl = 1; 

for (bowl = firstBowl: bowl < hisMancala: bowl++) 
if (boardfbowl] > 0) 

( 

StateOfGame result; 
long 1; 

dir = -1: 

//'fhc following trick speeds the whole program 
II up by about 1 percent... take it or leave it 
for (i =0; i < halfBoardSize; i++) 

((double*)worklngBoard) [i] 

((double*)board) [i]; 

result = DoMovel(workingBoard. boardSize, 
bowl, dir); 


“More than a decade 
of MacTech on CD!” 



for Utacintosb 
Programmers & Developers 



http:// WWW. mactech. com 


if ((depth == 0) I I (result = kGameOver)) 
value = workingBoard[myMancala] - 
workingBoard[hisMancala] ; 

else 

I 

if (result = kPlayAgain) 
value = AlphaBetal( 

depth - 1, workingBoard. 
boardStorage, boardSize, 
chosenBowl, chosenDirection, 
lowerBound, upperBound); 

else 

value = AlphaBeLa2( 

depth - 1. workingBoard. 
boardStorage. boardSize, 
chosenBowl. chosenDirection. 

- upperBound, - lowerBound); 


if (value > lowerBound) 

( 

bestBowi = bowl: 
bestDir = dir: 
lowerBound = value; 

if (lowerBound >= upperBound) 
break: 

I 

dir = 1; 

for (i = 0; i < halfBoardSize; i++) 

((double*)workingBoard)[i] = 

((double*)board)[i]: 

result = DoMovel(workingBoard. boardSize. bowl, dir); 
if ((depth =0) II (result = kGameOver)) 
value = workingBoard[myMancala] - 
workingBoard[hisMancala]: 

else 
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( 

if (result = kPlayAgain) 
value * AlphaBetal( 

depth - 1, workingBoard, 
boardStorage, boardSize, 
chosenBowl. chosenDirection, 
lowcrBound, upperBound); 

else 

value = - AlphaBeta2{ 

depth * 1, workingBoard. 
boardStorage, boardSize. 
chosenBowl, chosenDirection. 
- upperBound, - lowerBound); 

) 

if (value > lowerBound) 

( 

bestBowl = bowl; 

bestDir “ dir: 

lowerBound = value: 

if (lowcrBound >= upperBound) 
break; 

) 

I 

•chosenBowl = bestBowl; 

•chosenDirection “ bestDir; 
return lowerBound; 


AlphaBcta2 

long AlphaBeta2( 
long depth, 
long board[], 
long ‘boardStorage, 
const long boardSize, 
long ‘chosenBowl. 
long ‘chosenDirection. 
long lowerBound. 
long upperBound 

) 

( 

long rayMancala, hisMancala, firstBowl, halfBoardSize; 
long bowl, dir, value. bestBowl, bestDir; 
long ‘workingBoard: 

halfBoardSize “ boardSize / 2; 

workingBoard = boardStorage + depth * boardSize; 

myMancala = haifBoardSize: 

hisMancala = 0; 

firstBowl - myMancala + 1; 

for (bowl = firstBowl: bowl < boardSize: bowl-H-) 
if (board[bowll > 0) 

( 

long i, result; 
dir = -1; 

for (i “ 0; i < haifBoardSize; i-H-) 

((double*)workingBoard)[il = 

((double‘)board)[i]; 

result = L)oMove2 (workingBoard . boardSize, 
bowl, dir); 

if ((depth =0) II (result = kGameOver)) 
value • workingBoard LmyMancalaJ - 
workingBoardfhisMancala]: 

else 

( 

if (result kPlayAgain) 
value = AlphaBeta2( 

depth - 1, workingBoard. 
boardStorage, boardSize. 
chosenBowl. chosenDirection, 
lowerBound. upperBound); 

else 

value * AlphaBetal( 

depth 1, workingBoard. 
boardStorage, boardSize, 
chosenBowl, chosenDirection, 

- upperBound, - lowerBound); 

1 


if (value > lowerBound) 

I 

bestBowl = bowl; 
bestDir = dir; 
lowerBound = value; 
if (lowerBound >” upperBound) 
break: 

} 

dir = 1; 

for (i = 0: i < haifBoardSize; i-H-) 

((double*)workingBoard) [i] = 

((double*)board)[i]; 

result “ DoMove2(workingBoard. boardSize, 
bowl, dir); 

if ((depth = 0) II (result kGameOver)) 
value = workingBoard[myMancala] • 
workingBoard[hisMancala]: 

else 

( 

if (result = kPlayAgain) 
value AlphaBeta2( 

depth - 1. workingBoard. 
boardStorage. boardSize, 
chosenBowl. chosenDirection. 
lowerBound. upperBound); 

else 

value = - AlphaBetal( 

depth - 1. workingBoard, 
boardStorage. boardSize, 
chosenBowl, chosenDirection. 
upperBound, - lowerBound); 

1 

if (value > lowerBound) 

I 

bestBowl = bowl; 
bestDir = dir; 
lowerBound = value; 
if (lowerBound upperBound) 
break: 

) 

) 

•chosenBowl = bestBowl; 

‘chosenDirection = bestDir: 
return lowerBound: 


DropStoncsl 

r 

Boolean DropStonesQ 

Drops stones, return tnie if we get to play again 

-7 

inline Boolean DropStonesK 
long board[], 
const long boardSize. 
long bowl Played, 
long directionPlayed 


long myMancala. hisMancala, firstBowl, lastBowl: 
long stoneslnHand, nextBowl; 

myMancala = 0: 

hisMancala = boardSize / 2; 

firstBowl = 1; 

lastBowl = hisMancala - 1: 

stoneslnHand = board[bowlPlayedJ; 
board[bowlPlayed] = 0; 
nextBowl = bowlPlayed; 

/* Drop stones V 

while (stoneslnHand > 0) I 
nextBowl -»-= directionPlayed; 

if (nextBowl == hisMancala) 
nextBowl += directionPlayed: 
else 
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{ 

if (nextBowi < 0) 

nextBowl “ boardSize - 1: 

if (nextBowl = boardSize) 
nexlBowl * 0; 

) 

board[nextBowl] += 1; 
stonesInHand -= 1; 

} 

/* Perform capture 7 

if ((board[ncxlRowl] “ 1) && 

(nextBowi >= firstBowl) && 

(nextBowl <= lastBowl)) 

{ 

board [nextBowlJ “ 0: 
board[myMancalal +“ 

(1 + board[boardSize - nextBowlJ); 
board [boardSize - nextBowl! = 0; 

1 

/* Return true if gel to play again V 
return (nextBowl “ rayMancala): 


DropStoncs2 

inline Boolean DropSlones2( 
long board[J. 
const long boardSize. 
long bowlPlayed. 
long directionPlayed 

) 

i 

long myMancala, firstBowl, lastBowl: 
long StonesInHand, nextBowl; 

myMancala = boardSize / 2; 
firstBowl * myMancala + 1: 
lastBowl = boardSize - 1: 

StonesInHand " board[bowlPlayed] ; 
board[bowlPlayed] ” 0; 
nextBowl = bowlPlayed; 

/• Drop stones V 

while (stonesInHand > 0) I 
nextBowl += directionPlayed: 

if (nextBowl <“ 0) 

nextBowl ” boardSize - 1: 
else 

if (nextBowl = boardSize) 
nextBowi = 1: 
board[nextBowl] 1: 

StonesInHand -= 1: 

) 

/• Perform capture 7 

if ((board[nextBowl] — 1) && 

(nextBowl >= firstBowl) && 

(nextBowl <“ lastBowl)) 

I 

board [nextBowl] = 0; 
board[myMancala] +" 

(1 + board[boardsize - nextBowl]): 
board[boardSize nextBowl] “ 0; 

) 

/* Return true if get to play again 7 
return (nextBowl == myMancala); 


FirstSideEnipty 

r 

B(K)lean FirstSidcEmptyO 

Checks to see if first side has no stones left in it 

7 

inline Boolean FirstSideEmpty( 
long board[]. 
const long halfBoardSizc 

) 
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{ 

long bowl; 

for(bowl = halfBoardSlze 1; bowl > 0; bowl-) 
if (board[bowl] != 0) 
return false; 
return true; 


SccondSidclimpiy 

r 

Boolean SccondSidcEmptyO 

Checks to sec if first side has no stones left in it 

7 

inline Boolean SecondSideEmpty( 
long board[]. 
const long boardSize 

( 

long bowl; 

long halfBoardSize “ boardSize / 2; 
for(bowl * boardSize - 1; bowl > halfBoardSize; bowl ) 
if (board[bowl] != 0) 
return false; 
return true; 


RemainingToMancala 

r 

void RemainingToMantalaO 

Moves remaining stones on specified side into Mancala 

7 

inline void RemainingToMancala( 
long board[], 
const long boardSize, 
const Boolean playerOne 


long mancala, firsLBowl, lastBowl, bowl; 

if (playerOne) ( 
mancala =" 0; 
firstBowl = 1; 

lastBowl = boardSize / 2 1; 

) else ( 

mancala = boardSize / 2; 
firstBowl = boardSize / 2 + 1; 
lastBowl = boardSize * 1; 

) 

for(bowl = firstBowl: bowl <= lastBowl; bowl++) 

i 

board[mancala] += board[bowl]: 
board[bowl] = 0: 

1 


DoMovel 

r 

StateOfGamc DoMovcQ 

Drops the specified stones and cleans up the board 

if the game is over. 

«7 

inline StateOfGamc DoMovel( 
long board[], 
const long boardSize, 
long bowlPiayed, 
long directionPlayed 


Boolean getToPlayAgain: 

gotToPlayAgain = DropStonesl(board, boardSize, 
bowlPiayed. directionPlayed); 

if (FirstSideEmpty(board. boardSize / 2)) { 
RemainingToMancala(board, boardSize, false): 
return kGameOver; 

) 


if (SecondSideEmpty(board, boardSize)) ( 
RemainingToMancala(board. boardSize. true); 
return kGameOver; 

) 

if (getToPlayAgain) 
return kPlayAgain; 
else 

return kDefault; 


DoMovc2 

inline StateOfGarae DoMove2( 
long board[], 
const long boardSize, 
long bowlPiayed, 
long directionPlayed 


Boolean getToPlayAgain; 

getToPlayAgain = DropStones2(board, boardSize. 
bowlPiayed, directionPlayed); 

if (FirstSideEmpty(board, boardSize / 2)) ( 
RemainingToMancala(board, boardSize, false); 
return kGameOver; 

) 

if (SecondSideEmpty(board. boardSize)) ( 
RemainingToMancala(board, boardSize, true); 
return kGameOver; 

) 

if (getToPlayAgain) 
return kPlayAgain; 
else 

return kDefault; 


ClaimingVictory 

/* Bt)o!can CiaimingVicioryO 

Only called before returning from Mancala 
Docs not clean up the board 

7 

Boolean ClaimingVictory( 
long board[]. 
const long boardSize. 
const Boolean playerOne 

) 

I 

long bowl; 
long sum = 0; 

long halfBoardSize = boardSize / 2: 

if (FirstSideEmpty(board. halfBoardSize)) 

I 

for (bowl = halfBoardSize + 1; 
bowl < boardSize; bowl++) 
sum += board[bowl]; 
if (playerOne) 

return board[0] > (sum + board[halfBoardSize]); 
else 

return board[0] < (sum + board[halfBoardSize]) ; 

} 

if (SecondSideEmpty(board, boardSize)) 

( 

for (bowl = 1; bowl < halfBoardSize; bowl++) 
sum += board[bowl]; 
if (playerOne) 

return (board[0] + sum) > board[halfBoardSize] ; 
else 

return (board[0] + sum) < board[halfBoardSize]; 

1 

return false; 


■1 
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lUEWSBITS 


by Jessica Courlney 


AppMaker Improves Support for Apple’s Appearance 
Manager; Announces Mac OS X “Carbon” Plans 

Bowers Development announced that it is now shipping 
AppMaker CD #10. It is in the mail to all current subscribers, 
domestic and international. 

AppMaker’s view editor and simulator more fully support 
Apple’s Appearance Manager. It supports more kinds of c:ontrols 
and more options, such as bevel buttons with icon and text and 
menus; left and right icon buttons; clock controls; password 
fields; group boxes with the 3D look and with checkbox or 
popup titles; and Apple’s Tab Panels. 

Beyond building the user interface, AppMaker also helps users 
define the data engine pait of theii* programs. Users can define data 
items and connect them to user interface items. AppMaker #10 
supports more data types and also lets users define function 
members. AppMaker generates accessor functions for the data and 
generates code to Get and Set data values. 

For PowerPlant, AppMaker generates the compatibility 
classes rather than the old GA classes. PowerPlant at runtime 
decides whether to use the new Appearance controls or the old 
GA classes. For C-I-+, Af)pMakcr now generates dialogs as classes 
rather than procedural code. This provides the same IJI-Data 
interaction formerly available only with windows. It also 
simplifies some of the libraiy code for handling dialogs. 

The AppMaker-generated code is already more than 90% 
Carbon-compatible. Bowers plans to support Navigation Services 
in a release later this year. 'The few remaining incompatibilities 
will be updated as soon as Apple relea.se new APIs. 
<http://members.aol.com/bowersdev/> 

Web FM 4.0 SDK Now Available for FileMaker Pro 4.0 
Developer Edition 

Web Broadcasting is now shipping the WFB FM 4.0 
Solutions Distribution Kit (SDK) for FileMaker Pro 4.0 Developer 
Edition from FileMaker Inc. 

WEB FM 4.0 SDK allows unlimited, royalty-free distribution 
of the WEB FM 4.0 plug-in with the Macintosh runtime databa.se 
engine version of FileMaker Pro Developer Edition (or FileMaker 
Pro 3.0 SDK). FileMaker Pro 4.0 Developer Edition will include 
an enhanced version of the FileMaker Pro Rintime binding 
engine, which does not require end users to install a full copy of 
FileMaker Pro. With WEB FM 4.0 SDK, developers bind a version 
of WEB FM 4.0 to work with their run-time application. 

WEB FM 4.0 SDK provides FileMaker Pro developers with a 
fast,cost-effective way to compete in the Internet product space 
and distribute customized World Wide Web products to 
consumers. Enterprising FileMaker Pro developers can now 
distribute their desktop applications and solutions as powerful 


Internet or Intranet applications and .solutions. Current products 
that use the runtime database engine of FileMaker Pro and WEB 
FM SDK include Simply Suiveys, LOG FM, and FM@iler. 

Version 4.0 of WEB FM introduced easy-to-use, Internet 
standard Template files with context-sensitive [field name] token 
support. A breakthrough, highly intelligent parsing algorithm 
automatically selects pop-up/pull-down menu items and 
automatically checks radio button or checkbox elements using 
database record information. Other new, advanced features 
includes support for Virtual Hosts, add-on Processors, and 
enhanced record-level security. 

WEB FM 4.0 SDK includes the ability to assign auto- 
configured values for: 

• Suffix 

• Action 

• Creator extension 

• Settings file name 

• And more... 

WEB FM 4.0 SDK may be purcha.sed direct from Web 
Broadcasting for $1495 until July 31st, 1998. After July 31st, 
1998, pricing will be $1995. Upgrades from WEB FM 3.0 SDK 
are only $495. 

<http;//webfm.com/> 

Microspot To License 3D World Shared Library To 
Software Developers 

Microspot, longtime 3D developer, today announced the 
Microspot 3D World Developer Partner Program. Many 
application developers could enhance their products by 
including 3D, but this is a challenging and time consuming task. 
Microspot is now offering developers, who join the Microspot 3D 
World Developer Partner Program, access to 3D World 3.0 as a 
solution for Windows and Macintosh applications. Tliiough this 
program a developer may license code which is based upon 
Microspot’s 3D World 3.0 due for release in July 1998. 

3D World is designed as a completely modular 3D modeling 
and animation application. It is comprised of an application shell, 
and a shared libraiy (which acts as a C++ wrapper to QuickDraw 
3D, and provides numerous utility routines to aid development), 
functionality is add by way of plug-ins Microspot has written 
over 100 plug-ins which range from import and export to 
modeling to animation and navigation. Being based on 
QuickDraw 3D enables 3D World to make use of high end QD3D 
plug-in renders like those from LightWork Design. (See 
<http://www.diamondschmitt.com/beta4.html> for examples of how a 
renowned architect uses 3D World and LightWorks to produce 
awesome renderings of proposed buildings). 


72 


NewsBits 


MacTech • July 1998 








Microspot is making available for license the 3n World 
Plug-in API, Application API, Shared Library API, and C++ 
headers. Developers can license all or some of these 
components to write their own 3D world plug-ins, 3D 
applications or to integrate 3D into their existing applications. 
This enal)les them to address their own vertical markets and 
include their own content. 

Currently, there are four levels in the DPP program. 
Depending on the level at which developers join, they will 
receive technical support help and a large number of plug-ins to 
bundle with their application. Developers will be able to include 
a Powered by 3D World logo on their box, so their users will 
recognize the technology that the product is based upon. 
<http://www.microspot.com/clev> 

<http://www.macsourcery.com> 

Roundabout Logic, Inc. Ships Widgetizer 1.0 

Roundabout Logic, Inc. announced that it is now shipping 
the final version of Widgetizer 1.0, the ultimate tool for the 
creation of QuickTime VR Object Movies. The shipping 
product features a fresh look, including a new logo and 
brilliant retail package. Widgetizer 1.0 comes with a printed 
manual, as well as electronic tutorial and extensive samples of 
QuickTime VR. As an added bonus, Apple’s new QuickTime 
3.0 PRO is included FREE. 

Widgetizer is Roundabout Logic’s peerless rapid object 
editor for QuickTime VR. Widgetizer generates interactive QTVR 


object movies which look in at a central point, simulating the 
effect of holding an object in the hand and turning it around to 
view it from all angles. 

Widgetizer 1.0 is the most advanced program available for 
producing interactive QTVR Object movies for the web and 
multimedia presentations. The final exported Q'FVR movies are 
playable on both Macintosh and Windows PCs. Widgetizer 
features a user-friendly interface, definable hot-spots, custom 
backgrounds, frame-based animation, sound integration, image 
editor and supports all cameras and device software controlled 
QTVR object rigs. All the user adds is the creativity. 
<http://www.roundaboutlogic.com> 

Mac os Runtime for Java Debugging Update 

The recent release of MRJ 2.1 early access 1 on the Apple 
& Java web site <http://developer.apple.com/java/> did not 
support debugging with either Metrowerks CodeWarrior Pro 
or Symantec Visual Cafe. Apple has been working diligently 
to remove this limitation and we now have an update that 
enables debugging with Metrowerks CodeWarrior Pro 3. As 
soon as we have an update available for Symantec Visual 
Cafe, we will make it available as well. 

Note that this update does not work with earlier versions 
of CodeWarrior. 

<http://developer.apple.com/java/text/prerelease.html> 
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InterLok 

Sell Your Software Online 


Features: 

• Wraps your software in minutes 

• Mac & PC Compatability 

• Try-Before-You-Buy, Rentals & Immediate Sales 

• Localizable Interface 

• Unlimited Merchants 

• Key Disks 

• Unlock with your own website or with a licensed clearing house 


PACE Anti-Piracy 
1082 Glen Echo Ave. 

San Jose, CA 95125 

Phone; (408) 297-7444 
Fax: (408)297-7441 

Email: sales@paceap.com 

www.paceap.com 








by Jeff elites <online@mactech.com> 


Sweating the Details 

By virtue of the Mac’s user interface, all Macintosh 
applications are graphical in naaire, whether or not they have 
graphics as their actual subject matter. Some would go so far as 
to argue that on a Mac the interface is the whole point. So even 
if you are not developing the next Doom or Photoshop, you still 
have to think about the way things look on screen, and a well- 
designed interface can set a successful product apart from the 
competition. The actual appearance is only one aspect of 
effective interface design, but it is an important one, because it 
shapes a user’s first impression of your application. 

Fortunately, there are a wealth of shareware products 
available to help you tweak your interface until it is just how you 
want it, and to help you inspect the interfaces of other 
applications to see what they did right (or wrong). In the early 
days of Apple’s Grayscale Appearance, designers spent no end of 
time wondering what exact shade of gray certain applications 
used to achieve their subtle three-dimensional effect. It’s a simple 
question, but a difficult one to answer without the right tool. 
There are .several products which fill the need nicely, allowing 
you to view an arbitrary region of the screen at magnification, 
and determine the color of individual pixels. Check out 
ColorFinder, Color Picker Pro, ColorSieve, Coloristic, and Pixel 
Spy, and decide for yourself which you like best. 

ColorFinder 

<http://www.acmetech.com/FreeWares.html> 

Color Picker Pro 

<http://www.rootworks.com/cpp/> 

ColorSieve 

<http://members.aol.com/markwomack/colorsieve.html> 

Coloristic 

<http://www.bubblepop.com/coloristic/index.html> 

Pixel Spy 

<http://www2.trincoll.edu/~bhorling/pixelspy/> 

Screen Ruler is one of those unique applications which 
makes you wonder, “why didn’t I think of that?” It places a ruler 
on the screen, allowing you to measure distances down to the 
pixel. So if you have trouble remembering how wide a scroll bar 
is, you can just whip out Screen Ruler and see for yourself, and 
you can avoid eye strain by using it in conjunction with one of 
the previously mentioned magnifying glasses. 

Screen Ruler 

<http://www.kagi.com/microfox/> 


Although it is less often used in the interface itself, antialiasing 
can be an effective way to lend a more polished look to your 
application’s interface elements, or to its splash screen or About 
box. 1 wo excellent examples are the About box of Aaron Giles’ 
popular JPEGView image viewer and the button and text-field 
labels of Trygve Isaacson’s Hex Wrench programmer’s calculator, 
both of which use antialiasing of grayscale text. (And of course, 
these are useful tools to have around in their own right.) 

JPEGView 

<http://www.umich.edu/~archive/mac/graphics/graphic5util/jpegview3.31.sit.hqx> 

Hex Wrench 

<http://www.bombaydigital.com/HexWrench/> 

Antialiasing can be done on-the-fly, and there was an article 
in January 1997’s MacTech explaining how to do this using 
QuickDraw’s CopyBits routine. But you can also create 
antialiased images and text with an image editor, and use them 
within your application as you would any other PICT resource. 
Which technique is best depends on your situation, but the latter 
approach if often appropriate and has the advantage of allowing 
you to use nonstandard fonts without requiring the user to have 
them installed. An excellent shareware application for this sort of 
thing is Thorsten Lemke’s GraphicConverter. 

Antialiasing with Color QuickDraw 

<http://www.mactech.com/articles/mactech/Vol. 13/13.01 /QD-Antialiasing- 
Techniques/text.htmb 

GraphicConverter 

<http://www.lemkesoft.de/index.html> 

When it comes time to put the finishing touches on your 
new application, you just have to have a cool icon. If you’d like 
to use a tool which is a little more powerful than ResEdit, take a 
look at Icon Machine — it’s full of nifty features. 

Icon Machine 

<http://www.kagi.com/dathorc/iconmachine.html> 

Image Formats 

With the advent of QuickTune, programmers don’t have to 
worry about the details of various file formats just to gel an image 
onto the screen. Even so, sometimes you do need to know what 
makes a JPEG a JPEG and a TIFF a TIFF, and how to handle them 
on your own. O’Reilly maintains the Graphical Data Standards 
and File Formats page as a companion to their book 
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Encyclopedia of Graphics File Formats, and it has links to 
information on a wide range of image formats. For things not 
covered here, head over to Wotsit’s File Format Collection, 
which has a massive assemblage of information on just about 
any file format you are likely to encounter, including image 
formats but not limited to them. 

Graphical Data Standards and File Formats 

<http://www.ora.com/centers/gff/specs.htm> 

Wotsit's File Format Collection 
<http://www.wotsit.clemon.co.uk/> 

For .specific information on JPEG (the Joint Photographic 
Experts Group format), the official JPEG home page has a 
collection of links to useful information. For TIFF (the Tagged 
Image File Format), there is the Unofficial TIFF Home Page. 
Finally, there is PNG (the Portable Network Graphics format), 
which is gaining in popularity as a free replacement for the 
proprietaiy GIF format for lossless compression. Its home page 
is full of personality, giving the history of PNG as well as listing 
its strengths and spelling oul the technical details. Macintosh 
versions of code to work with each of these formats is available 
on Jack Jansen’s page. 

JPEG Related Links 

<http://www.jpeg.org/public/jpeglinks.htm> 

The Unofficial TIFF Home Page 
<http://home.earthlink.net/~ritter/tiff/> 

PNG Home Page 

<http://www.cclrom.com/pub/png/> 

Jack's Macintosh Software 
<http://www.cwi.nl/~jack/macsoftware.html> 


"IN JUST A FEW SECONDS I’VE SUCCESSFULLY TRACKED 
DOWN A MEMORY CORRUPTION BUG THAT HAS BEEN ELUD¬ 
ING ME FOR ABOUT 3 MONTHS. FANTASTIC I-)" 

-Bryan Christianson- 



The #1 Macintosh bug detection tool! 


FREE 

REMO 


Detect memory leaks automatically 
Instruction level bounds checking 
Validate 400 Mac Toolbox calls 
Pinpoint stale handle usage 

Integrated with all Mac debuggers 
Debug shlibs and^tand alone code 
Faster than ever^bffgre 
Jhuiiiit 




941.795.7801 Fax: 941.795.5901 
www.onyx-tech.com sales@onyx-tech.com 


These and other links are available from the MacTeeh 
Online web pages at <http://www.tnactech.com/online/>. ^ 


Dilbert® by Scott Adams 


r\Y EGO ??... SHOULDN'T 

YOU BE INSIDE r\E 

SOnEPLACE ? 


} VIELL,YE5, 

n 

NORMALLY WE 

1 EGOS FEED 

' WITHIN THE 


^ BODY. A 

M 

r ^^6 


©1998 United Feature Syndicate, Inc. (NYC) 




50 Wrt^T THE HECK 
ARE YOU DOING OUT 
HERE? 


YOU'RE STARVING 
ME, HAN. 1T\ 
GOING TO TRY OUT 
FOR A PLAY |V 
ORSOHE- f\ 
THING. 


July 1998 • MacTech 


MacTech Online 


75 
























TIPS & 
TIDBITS 


by Steve Sisak 


Here is a code to draw rotated QuickDraw picture without 
QuickDraw GX. 


descHnd = 

(ImageDescriptionHandle):iNewHandleClear 

(sizeof(ImageDescription)); 

if (descHnd — nil) goto rtii; 


You can find the project files at 

<http://www.bekkoame.or.jp/-iimori/tmp/StdPix.hqx> 


// 

// Rotate QuickDraw picture with StdPix bottleneck pn)ccdure. 

// 

//include <ImageCompression.h> 

//include <GXMath. h> // flOJTO macros 

//incl ude <stdio .h> // use SIOUX window to draw on 

void mainO 


enum ( 

kBWSmailMacOSLogo = 16501. //use MacOS lx)go 

kSmallMacOSLogo = -16503. 

kBigMacOSLogo » -16506 


Ficllandle picHnd = nil; 

ImageDescriptionHandle dc.scHnd = nil; 


( 

ImageDcscripti on& desc = *‘descHnd; 


desc.idSize 

desc.cType 

desc.temporalQuality= 

desc.spatialQuality = 

desc.width 

desc.height 

desc.hRes 

desc.vRes 

desc.dataSize 

desc.f rameCount 

desc.depth 

desc.clutID 


sizcof(TmageDescription); 
kQuickDrawCodecType; 
codecLosslessQualIty; 
codecLosslessQuality: 
picRect.right - picRect.left; 
picRect.bottom - picRect.top; 
ff(72); 
ff(72); 

::GciHandlcSize((Handle)picHnd); 
1 ; 

32; 

• 1 ; 


::HLock((Handle)picHnd); 

PixMap pixMap; 

err = ::SetCompressedPixMaplnfo 

(&pixMap.descHnd, * (llandle)picHnd,0,nil .nil); 
if ( err ) goto rtn; 


p r i n t f (" \ n ”) I // initialize Toolbox 

:iSetPort(::FrontWindow()): 

long response; // examine Quicklime existence 

OSErr err = :;Geslalt(gestaltQuickTime.&response); 
if( err ) goto rtn; 

Codecinfo codecinfo; // examine QuickDrawCodec existence 
err ” 

:;GetCodecInfo(&codecTnfo,kQuickDrawCodecType,anyCodec); 
if( err ) goto rtn; 

picHnd = :rCetPicture(kSmallMacOSLogo); 
if (picHnd = nil) goto rtn; 

::HNoPurge((Handle)picHnd); 

;:DetachResource((Handle)picHnd); 

Rod picRect = (“picHnd) .picFrame; 

MatrixRecord matrix; 

: :SetIdentityMatrix(&matrix); 

Rect r(picRect); 

:lOffsetRect(&r,40 - r.left,40 - r.top); 

: :RectMatrjx(6matrix,&picRect,&r) ; //move to(40,40) 

; :RolatoMatrix(6matrix,ff (30), //rotate 30degree 
ff((r.left + r.right)/2), 
ff((r.top -r r .bottom)/2)) ; 


StdPixUPP uppStdPix; 

const CQDProcs ‘CQDProcPlr " 

((CGrafPtr)qd.ihePort)->grafProcs; 

if( CQDProcPtr ) { 

UppStdPix *= (StdPixUPP)CQDProcPtr->newProcl; 

)else! 

CQDProcs .stdProcs; 

::SetStdCProcs(&stdProcs) ; 

uppStdPix = (StdPixUPP)stdProcs.newProcl; 

] 

CallStdPixProc(uppStdPix.&pixMap.&picRect.^matrix.ditherCopy, 

nil.nil.nil.cal101dBits|callStdBits); 
rtn: 

if ( descHnd ) { 

::DisposeHandle((Handle)descHnd); 

) 

if ( picHnd ) 1 

:;KillPicture(picHnd); 

) 

) 


Hideaki lirnori 
< iimon@lih. hekkoame. or.jp> 

m 


Send us your tips or we’ll install EvenBetterBusError on your machine! On the other hand, we might just pay you $25 for each tip we use, or $50 for Tip of 
the Month. You can take your award in goods, subscriptions or US$. Make sure any code compiles, and send tips (and where to mail your winnings) to our 
Tips e-mail address at ■ 
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Macintosh 
Development News ^ 

The site has all the current • 
breaking news in the * 

development community * 
and even archives past 
news pieces. 


Search the Site 

Search and find that 
article, news piece or 
source code you're 
looking for via the new 
Phantom search engine 
courtesy of Maxum. 


Article Archives •*’ 

These archives have 
ithousands of pages of 
content in them from the 
histories of MacTech, 
MacTutor, develop, and 
Frameworks magazines. ,*•* 
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develop 


The entire history of 
develop, Apple's award 
winning technical journal. 
iSiThat is 29 issues from 
1990-1997. 
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Macintosh Development News 


1 2/02/9 / PR : Metrowcrks Announces First Quarter 1998 
Revenues of US$6.2 Million 

12/02/97 PR : WebSTAR PoverKey Pro Tickler 

12/02/9 / PR : The Association of Macintosh Trainers 

12/01/97 PR : Apple Announces WebObjects 3.5 


The MacTech CD-ROM nov includes 
every article available from every 
najor Mac developer 
publication all in THINK Reference 
format. 


develop, Apple's avard vinning 
technical journal, Is nov part of 
MacTech. See the entire develoD 
archives like you neveoT 
before. • * 


Current 


ClldooH this month's cover for all 
fldf^einfoon MacTech I 


our net is done 
^ ► Leo al/DlscUlmers 
► Vebmast^r 
Feedback 



12/01 /9 / PR : Apple Delivers Public QuickTime 3.0 Developer 
Preview Release 

12/01/97 PR : Roaster Technologies Licenses ObjectSpace 
Voyager As Primary Java Interface For Distributed Computing 

11/25/97 PR ; Apple, BLaCKSMITH Offer Classes On Creating 
Dynamic Web Applications 

11/25/97 PR : Bridge Allows Mac Webmasters to Easily Upgrade 
from Command Tags to XML 

11/25/97 PR : Joy Introductory Offer Expires This Week 
11/25/97 PR ; Pyromanial Pro 

1 1/24/97 PR : SpotCheck, the Program Editor That Knows Java 
11/24/97 PR : SiteWarrior Wages War On Web Site Complexity 

I I /24/97 PR : Objective-Everything Release 5 

II /24/97 PR : Maxum Development Announces Release Of 
NetCloak 2 5 Upgrade 

1 I /24/97 PR : Build Counter Tool for Tracking Number of 
Builds 

11/20/97 PR : Object Plant Version 1.4.4 
News prior to t 1 /20/97.. 

Search News... 


Search j 


Advanced Search 


Need an answer on a programming 
question? Check out our complete 
archives - - thousands of pages - - 
including MacTech, MacTutor, 
develop and FrameWorks. 
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CLASSIFIEDS 


Senior Software Engineer 


With 3 Techn'Kol Emmy Awards, Scitex Digital Video, Inc. leads the video industry 
with innovative digital solutions for professional video postproduction, effects gener¬ 
ation and multimedia development. We offer the broodest range of fully real time 
solutions for opplications from desktop to broadcast os well os cool careers at our 
Northern California operations. 

Our Grass Valley organization seeks a team-oriented Senior Software Engineer with 
strong interpeRonal skilk to design and develop non-linear video editing applicotions 
running under Mocintosh or Windows NT operating system environments. To quolify, 
you should hove a BSCS, BSEE or equivalent and 5 years experience in the design, 
test ond delivery of applicotions in Mocintosh, Windows NT/95 or Win32. The abil¬ 
ity to work effectively both independently and as part of a team Is essential. Desired 
skilk/experience include: knowledge of d'lgitol oudio oppTications development, 
experience with video compression technology and porting applications from 
Macintosh to Windows NT ond an understonding of image processing algorithms. 

Scitex Digital Video offers an excellent solory and benefits packoge with the chance 
to make an impact on the exciting broadcast industry. For immediate consideration, 
mail your resume to: Scitex Digital Video, Inc., 431 Crown Point Circle, Suite 150, 
Grass Valley, CA 95945, fax it to (530) 272-9801 or email to hr@scitexdv.com. 
Check us out on the web at www.scitexdv.com. An equal opportunity employer. 

scitex.r5l,. 
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Professional Software Developers 

Looking for career opportunities? 
Check out our website! 

Nationwide Service 
Employment Assistance 
Resume Help 
Marketability Assessment 
Never a fee 

Scientific Placement, Inc. 

800-231 -5920 800-757-9003 (Fax) 

das@scientilic.com 



The Law Office of Bradley M. Sniderman 


California Lawyer focusing on Intellectual 
Property, Corporate, Commercial and 
Cx>ntract law, as well as Wills and Trusts. 


If you are looking to protect your software 
with Copyright or Trademark protection, 
or if you need help establishing or 
maintaining you business, please give me a 
call or an e-maiL Reasonable fees. 

(310) 553-4054 
brad @ sniderman.com 
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And, you know the address! 
http://www.devdepot.com 
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ith the right tools and the right team, you can build 
what you can dream. Create and communicate daring 
new concepts. The doors are wide-open, technology 
Is changing, and everything is possible. 


Everything’s evolving this year. MACWORLD Expo 
enters the Big Apple in style. Come to the center of 
the creative universe, home of Silicon Alley, for the 
industry’s foremost market event. Hear hundreds 
of fresh ideas for: 

■ Graphic design, commercial art and advertising 

■ Publishing and printing 

■ Education, research and development 

■ Motion picture, video and multimedia production 

■ Web site design and navigation 

MiiciiiORiDEp-iiiemiueuioriii is your opportunity 
to learn about the latest issues and technologies in 
these areas, including new operating systems and 
cross-platform applications. Meet industry experts 
and make essential connections. And take away 
the blueprints for a creative new world. 


Owned by: 


Sponsored by: 


Mawiorll MacwHK 

Managed by: IDG Expo Management Company 
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2. caii800-PSTI!fOor 

3. To receive oiore ifllorioailoR. 
cooipieie me coopon oo me rism. 


Ql YES! Tell me more about MACWORLD Expo ‘98 in New York. 

I’m interested in d Attending Q Exhibiting 

Name _Title 



Company_ 

Address_ 

City/State/Zip_ 

Phone_ email_ 

Mail to: MACWORLD Expo, 1400 Providence Highway, RO. Box 9127, Norwood, MA 02062 Fax to: 781-440-0357 

THIS IS NOT A REGISTRATION FORM 














































The Shaorpest Tool On 
The Cutting Edge Of 
Web Database Design 


"I^ssd's strengths are its extensive 
huHl-in commerce and e-mail features." 

MfltWEF.K 

"With excellent support for advanced 
FileMaker Pro features, outstanding 
formatting control, fast performance, 
and thorough documentation. Lasso 
is a datahase-puhlishing demon." 

Mackvorld Magazine 
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The UWn»a“ 
pileMaker* Pro Web 
l>evelopn»«"* Tool 


“liisso has proven to he a great resource 
for the Mac OS Software f’r Hardware 
Guide. We are verg impressed with the 
speed of the searches in a database of 
this size Your company support has 
been great tool" 

Gayle Westbrook 
Software & I lardware Guide 
Product Manager at 
Apple Computer 


Lflsso simply blows Tango out of the water" 
Paul Marly 
University of Illinois 


The Ultimate FileMaker* Pro 
Ufeb Development Tool 


Why do scores of high-profile websites rely on Lasso? Why is a portion of Lasso technology 
embedded in FileMaker Pro 4.0's Web Companion? With a feature set described as incredible, 
find out for yourself why Lasso 2.5 is the sharpest tool for creating online stores, discussion 
groups, response forms and countless other robust dynamic Web applications. 

Over 50 new tags including math, string and variable allow unparalleled data handling 
capability. Combined with an SSL server. Lasso allows for secure data transactions. Create 
embedded operations with the powerful inline command. Instantly upgrade FileMaker 4.0 
CDML tags to LDML with the Lasso Tag Converter. What's more, Lasso 2.5 Server edition 
supports multi-homing and offers superior performance over other Web servers. 

Find out today why Lasso is the award-winning tool which sets the standard for Mac OS 
dynamic Web database publishing. To order or for a reseller near you. please call 
425.646.0288. Download your free test drive version today at 
http://www.blueworld.com/lasso/download/. 


blueworld 


bringing business to the internet 
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